delivery_note

A delivery note documents goods handed to a customer or site. Each line is booked by its own issue movement with delivery_note_id set; the note itself does not change stock.

Mutable, so that signatures can be added after issue; the version with the greater hlc wins.
Ids: random UUIDs.
The reference app never deletes delivery notes.

Fields

Field	Type	Writer	Default	Meaning
`number`	string	required		Number as printed, see Number ranges
`recipient_id`	uuid	required		The recipient (customer or site)
`recipient`	object	required		Copy of the recipient at issue, see below
`reference`	string?	optional	none	The recipient's reference, for example an order number
`note`	string?	optional	none	Remark printed below the items
`issued_at`	date-time	required		Time of issue
`issued_by`	string?	optional	none	Display name of the person who issued it
`items`	array	required	`[]`	The lines, see below
`signatures`	array?	optional	`[]`	At most one per role, see below
`pdf`	sha256?	optional	none	Attachment: the rendered PDF
`template_hlc`	hlc?	optional	none	`hlc` of the delivery note template (`document_template` `...0002`) when the note was issued; null when no template record existed

The reference server checks none of the fields as required; the reference app does not show a note without number, recipient_id, recipient.name or issued_at, or with an item or signature that lacks one of its required fields.

recipient (copy)

Field	Type	Writer	Meaning
`kind`	string?	optional	`customer`, `site` or `employee`
`name`	string	required
`number`, `street`, `postal_code`, `city`, `country`, `contact`	string?	optional	As in the recipient record at the time of issue

phone, email and erp_reference are not copied.

items[]

Field	Type	Writer	Meaning
`position`	integer	required	Line number, starting at 1
`article_id`	uuid	required	The article
`sku`	string	required	Copy of the item number at issue
`name`	string	required	Copy of the article name at issue
`unit`	string	required	Copy of the unit at issue
`quantity`	number	required	Quantity issued
`from_location_id`	uuid	required	Where the goods left stock
`location_code`	string	required	Copy of the location code at issue
`serials`	array of string	required	Serial numbers issued with this line; `[]` for articles without serial tracking
`barcode`	string?	optional	First barcode of the article at issue, for the barcode column
`movement_id`	uuid	required	The `issue` movement that booked this line

signatures[]

Field	Type	Writer	Meaning
`role`	string	required	`recipient` (the person receiving the goods) or `issuer` (the person handing them out). Readers ignore entries with other roles.
`name`	string	required	Name of the person who signed, as typed
`signed_at`	date-time	required	When it was signed
`image`	sha256	required	Attachment: PNG of the signature

The reference app keeps the recipient's signature first. Adding a signature for a role replaces an existing one of that role.

Life cycle

Issue. The device writes one issue movement per line (with delivery_note_id and the note number in note), then the note with items[].movement_id pointing to them, signatures captured so far, the rendered pdf and template_hlc.
Sign later. A signature added later produces a new version of the note with the signature appended (or replaced) and a newly rendered pdf. The movements stay as they are.
Nothing else changes a note. Goods that come back are booked as receipts; the note stays as issued.

See Delivery notes for the full workflow with all records.

Rendering

Clients render the PDF from the note, the company profile and the delivery note template. A client that cannot download pdf (not synced yet) may render it again from the record; the result can differ in details when the template or the company profile changed since issue. template_hlc tells a client which template version the stored PDF was made with.

Server validation

Field	Rules
`number`, `reference`, `note`, `issued_by`	nullable, string
`recipient_id`	nullable, UUID
`recipient`	nullable, object
`issued_at`	nullable, date
`items`	nullable, list of objects
`items.*.position`	nullable, integer
`items..article_id`, `items..from_location_id`, `items.*.movement_id`	nullable, UUID
`items.*.quantity`	nullable, numeric
`items.*.serials`	nullable, list; each element a string
`signatures`	nullable, list of objects
`signatures.*.role`	nullable, one of `recipient`, `issuer`
`signatures.*.signed_at`	nullable, date
`signatures.*.image`, `pdf`	nullable, string matching `^[0-9a-f]{64}$`
`template_hlc`	nullable, string matching the stamp pattern

Example

{
  "entity": "delivery_note",
  "id": "9B4D6F18-2A7C-4E3B-8D51-6F0A2C4E8B73",
  "op": "upsert",
  "hlc": "001791800100000-0001-3F2A9C1B",
  "data": {
    "number": "LS-2026-3F-0007",
    "recipient_id": "5E2A8C14-9D3B-4A7F-B6C0-1E4D7F2A9B35",
    "recipient": {
      "kind": "site",
      "name": "Northring construction site",
      "number": "K-10042",
      "street": "Northring 12",
      "postal_code": "10115",
      "city": "Berlin",
      "country": "Germany",
      "contact": "Max Mustermann"
    },
    "reference": "Order 2026-118",
    "issued_at": "2026-10-12T10:15:00Z",
    "issued_by": "Erika Mustermann",
    "items": [
      {
        "position": 1,
        "article_id": "8C1F3D2E-5B7A-4A61-9F0E-2B4C6D8E0A13",
        "sku": "100101",
        "name": "Wireless access point AP-7",
        "unit": "Stk",
        "quantity": 4,
        "from_location_id": "2B0E6C1A-7D44-4F1B-9C3E-5A8D2F6B1C07",
        "location_code": "N-A01",
        "serials": [],
        "barcode": "4012345678901",
        "movement_id": "1D5F7A93-6C2E-4B8D-A0F4-8E3B5C7D9A26"
      }
    ],
    "signatures": [
      {
        "role": "recipient",
        "name": "Max Mustermann",
        "signed_at": "2026-10-12T10:16:00Z",
        "image": "acc6bcb1913432eed9c60781607713d63c802ff23893d35b88b1903ed04c2f50"
      }
    ],
    "pdf": "c99cb4424e483419efb1abf7772d7e47ec6de50715b1004641b0f9858362015c",
    "template_hlc": "001791792000123-0000-3F2A9C1B"
  }
}

Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Delivery note",
  "description": "Issued goods document. Mutable so that signatures can be added later; the version with the greater hlc wins. The items are booked as separate issue movements that reference the note. The reference server only checks the types of the fields it knows; the reference app does not show a note that lacks a field marked as required here.",
  "type": "object",
  "required": ["number", "recipient_id", "recipient", "issued_at", "items"],
  "$defs": {
    "uuid": {
      "type": "string",
      "format": "uuid",
      "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$"
    },
    "optionalSha256": {
      "type": ["string", "null"],
      "pattern": "^[0-9a-f]{64}$"
    },
    "signature": {
      "description": "A handwritten signature captured on the device.",
      "type": "object",
      "required": ["role", "name", "signed_at", "image"],
      "properties": {
        "role": { "description": "recipient: the person receiving the goods or borrowing the equipment. issuer: the person handing them out or taking them back.", "type": "string", "enum": ["recipient", "issuer"] },
        "name": { "description": "Name of the person who signed, as typed.", "type": "string" },
        "signed_at": { "type": "string", "format": "date-time" },
        "image": { "description": "SHA-256 of a PNG attachment with the signature.", "type": "string", "pattern": "^[0-9a-f]{64}$" }
      },
      "additionalProperties": true
    },
    "recipientCopy": {
      "description": "Copy of the recipient at the time of issue, printed on the document. It does not change when the recipient record changes later.",
      "type": "object",
      "required": ["name"],
      "properties": {
        "kind": { "type": ["string", "null"], "enum": ["customer", "site", "employee", null] },
        "name": { "type": "string" },
        "number": { "type": ["string", "null"] },
        "street": { "type": ["string", "null"] },
        "postal_code": { "type": ["string", "null"] },
        "city": { "type": ["string", "null"] },
        "country": { "type": ["string", "null"] },
        "contact": { "type": ["string", "null"] }
      },
      "additionalProperties": true
    }
  },
  "properties": {
    "number": { "description": "Document number as printed, from device numbering or a reserved server number.", "type": "string" },
    "recipient_id": { "description": "The recipient record (customer or site).", "$ref": "#/$defs/uuid" },
    "recipient": { "$ref": "#/$defs/recipientCopy" },
    "reference": { "description": "The recipient's reference, for example an order number.", "type": ["string", "null"] },
    "note": { "description": "Remark printed below the items.", "type": ["string", "null"] },
    "issued_at": { "type": "string", "format": "date-time" },
    "issued_by": { "description": "Display name of the person who issued the note.", "type": ["string", "null"] },
    "items": {
      "description": "The lines, each booked by its own issue movement.",
      "type": "array",
      "items": {
        "type": "object",
        "required": ["position", "article_id", "sku", "name", "unit", "quantity", "from_location_id", "location_code", "serials", "movement_id"],
        "properties": {
          "position": { "description": "Line number, starting at 1.", "type": "integer" },
          "article_id": { "$ref": "#/$defs/uuid" },
          "sku": { "description": "Copy of the article's item number at issue.", "type": "string" },
          "name": { "description": "Copy of the article's name at issue.", "type": "string" },
          "unit": { "description": "Copy of the article's unit at issue.", "type": "string" },
          "quantity": { "type": "number" },
          "from_location_id": { "$ref": "#/$defs/uuid" },
          "location_code": { "description": "Copy of the location's code at issue.", "type": "string" },
          "serials": { "description": "Serial numbers issued with this line; an empty list for articles without serial tracking.", "type": "array", "items": { "type": "string" } },
          "barcode": { "description": "First barcode of the article at issue, printed in the barcode column.", "type": ["string", "null"] },
          "movement_id": { "description": "The issue movement that booked this line.", "$ref": "#/$defs/uuid" }
        },
        "additionalProperties": true
      }
    },
    "signatures": {
      "description": "At most one signature per role. Absent or null means none.",
      "type": ["array", "null"],
      "items": { "$ref": "#/$defs/signature" },
      "default": []
    },
    "pdf": { "description": "SHA-256 of the rendered PDF attachment; rendered again whenever a signature is added.", "$ref": "#/$defs/optionalSha256" },
    "template_hlc": {
      "description": "hlc of the delivery note template (document_template 00000000-0000-4000-8000-000000000002) at the time of issue; null when no template record existed.",
      "type": ["string", "null"],
      "pattern": "^[0-9]{15}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{8}$"
    }
  },
  "additionalProperties": true,
  "examples": [
    {
      "number": "LS-2026-3F-0007",
      "recipient_id": "5E2A8C14-9D3B-4A7F-B6C0-1E4D7F2A9B35",
      "recipient": {
        "kind": "site",
        "name": "Northring construction site",
        "number": "K-10042",
        "street": "Northring 12",
        "postal_code": "10115",
        "city": "Berlin",
        "country": "Germany",
        "contact": "Max Mustermann"
      },
      "reference": "Order 2026-118",
      "issued_at": "2026-10-12T10:15:00Z",
      "issued_by": "Erika Mustermann",
      "items": [
        {
          "position": 1,
          "article_id": "8C1F3D2E-5B7A-4A61-9F0E-2B4C6D8E0A13",
          "sku": "100101",
          "name": "Wireless access point AP-7",
          "unit": "Stk",
          "quantity": 4,
          "from_location_id": "2B0E6C1A-7D44-4F1B-9C3E-5A8D2F6B1C07",
          "location_code": "N-A01",
          "serials": [],
          "barcode": "4012345678901",
          "movement_id": "1D5F7A93-6C2E-4B8D-A0F4-8E3B5C7D9A26"
        }
      ],
      "signatures": [
        {
          "role": "recipient",
          "name": "Max Mustermann",
          "signed_at": "2026-10-12T10:16:00Z",
          "image": "acc6bcb1913432eed9c60781607713d63c802ff23893d35b88b1903ed04c2f50"
        }
      ],
      "pdf": "c99cb4424e483419efb1abf7772d7e47ec6de50715b1004641b0f9858362015c",
      "template_hlc": "001791792000123-0000-3F2A9C1B"
    }
  ]
}