diff --git a/docs/api/openapi.json b/docs/api/openapi.json index dbaab61..09f0142 100644 --- a/docs/api/openapi.json +++ b/docs/api/openapi.json @@ -4119,7 +4119,7 @@ "Delivery" ], "summary": "Create delivery", - "description": "Creates a goods receipt with header and lines in one transaction.\nEach line requires `sku`, `amount`, `net`, and `tax` (rate).\n`rebate` defaults to `0`; `transactedAmount` defaults to `amount`.\n", + "description": "Creates a goods receipt with header and lines in one transaction.\nThe manifest `number` is allocated automatically via\n`nextNumber('delivery')`; the user-supplied reference is stored as\n`externalNumber`. Each line requires `sku`, `amount`, `net`, and\n`tax` (rate). `rebate` defaults to `0`; `transactedAmount` defaults\nto `amount`.\n", "security": [ { "cookieAuth": [] @@ -4133,13 +4133,14 @@ "schema": { "type": "object", "required": [ - "number", + "externalNumber", "date", "lines" ], "properties": { - "number": { - "type": "string" + "externalNumber": { + "type": "string", + "description": "User-supplied reference number" }, "date": { "type": "string", @@ -4157,7 +4158,7 @@ } }, "example": { - "number": "DHL-123", + "externalNumber": "DHL-123", "date": "2026-08-10", "supplierId": 1, "lines": [ @@ -4318,7 +4319,7 @@ "Delivery" ], "summary": "Update delivery", - "description": "Patches header fields that are present. If `lines` is present, replaces\nall lines; if omitted, leaves lines unchanged. Returns the full delivery.\n", + "description": "Patches header fields that are present. The manifest `number` is\nauto-allocated and cannot be patched; only the user-supplied\n`externalNumber` reference is editable. If `lines` is present,\nreplaces all lines; if omitted, leaves lines unchanged.\n", "security": [ { "cookieAuth": [] @@ -4342,8 +4343,10 @@ "schema": { "type": "object", "properties": { - "number": { - "type": "string" + "externalNumber": { + "type": "string", + "nullable": true, + "description": "User-supplied reference number (empty/null clears it)" }, "date": { "type": "string", @@ -4361,7 +4364,7 @@ } }, "example": { - "number": "DHL-124", + "externalNumber": "DHL-124", "lines": [] } } @@ -8804,7 +8807,8 @@ "type": "integer" }, "number": { - "type": "string" + "type": "string", + "description": "Auto-allocated via nextNumber('delivery')" }, "type": { "type": "string", @@ -8817,6 +8821,11 @@ "nullable": true, "description": "manifest.entity_id" }, + "externalNumber": { + "type": "string", + "nullable": true, + "description": "User-supplied reference number" + }, "date": { "type": "string", "format": "date-time" diff --git a/docs/api/routes/delivery/create.md b/docs/api/routes/delivery/create.md index 7fb09c9..5b98082 100644 --- a/docs/api/routes/delivery/create.md +++ b/docs/api/routes/delivery/create.md @@ -5,15 +5,18 @@ Protected. Requires a valid session cookie (`credentials: 'include'`). Create delivery Creates a goods receipt with header and lines in one transaction. -Each line requires `sku`, `amount`, `net`, and `tax` (rate). -`rebate` defaults to `0`; `transactedAmount` defaults to `amount`. +The manifest `number` is allocated automatically via +`nextNumber('delivery')`; the user-supplied reference is stored as +`externalNumber`. Each line requires `sku`, `amount`, `net`, and +`tax` (rate). `rebate` defaults to `0`; `transactedAmount` defaults +to `amount`. ## Body (JSON) ```json { - "number": "DHL-123", + "externalNumber": "DHL-123", "date": "2026-08-10", "supplierId": 1, "lines": [ @@ -38,6 +41,7 @@ Created delivery "number": "…", "type": "delivery", "supplierId": 1, + "externalNumber": "…", "date": "2026-08-10T00:00:00.000Z", "lines": [ { diff --git a/docs/api/routes/delivery/get.md b/docs/api/routes/delivery/get.md index d7773c7..ce45459 100644 --- a/docs/api/routes/delivery/get.md +++ b/docs/api/routes/delivery/get.md @@ -23,6 +23,7 @@ Delivery "number": "…", "type": "delivery", "supplierId": 1, + "externalNumber": "…", "date": "2026-08-10T00:00:00.000Z", "lines": [ { diff --git a/docs/api/routes/delivery/list.md b/docs/api/routes/delivery/list.md index c0d9a3a..7e8cc2e 100644 --- a/docs/api/routes/delivery/list.md +++ b/docs/api/routes/delivery/list.md @@ -20,6 +20,7 @@ Delivery list "number": "…", "type": "delivery", "supplierId": 1, + "externalNumber": "…", "date": "2026-08-10T00:00:00.000Z" } ] diff --git a/docs/api/routes/delivery/update.md b/docs/api/routes/delivery/update.md index 4fa9c7a..5a56ae7 100644 --- a/docs/api/routes/delivery/update.md +++ b/docs/api/routes/delivery/update.md @@ -4,8 +4,10 @@ Protected. Requires a valid session cookie (`credentials: 'include'`). Update delivery -Patches header fields that are present. If `lines` is present, replaces -all lines; if omitted, leaves lines unchanged. Returns the full delivery. +Patches header fields that are present. The manifest `number` is +auto-allocated and cannot be patched; only the user-supplied +`externalNumber` reference is editable. If `lines` is present, +replaces all lines; if omitted, leaves lines unchanged. ## Path parameters @@ -18,7 +20,7 @@ all lines; if omitted, leaves lines unchanged. Returns the full delivery. ```json { - "number": "DHL-124", + "externalNumber": "DHL-124", "lines": [] } ``` @@ -34,6 +36,7 @@ Updated delivery "number": "…", "type": "delivery", "supplierId": 1, + "externalNumber": "…", "date": "2026-08-10T00:00:00.000Z", "lines": [ { diff --git a/src/api/openapi.js b/src/api/openapi.js index 1644eaa..662d3da 100644 --- a/src/api/openapi.js +++ b/src/api/openapi.js @@ -247,6 +247,7 @@ * type: integer * number: * type: string + * description: Auto-allocated via nextNumber('delivery') * type: * type: string * enum: [delivery] @@ -254,6 +255,10 @@ * type: integer * nullable: true * description: manifest.entity_id + * externalNumber: + * type: string + * nullable: true + * description: User-supplied reference number * date: * type: string * format: date-time diff --git a/src/api/routes/delivery.js b/src/api/routes/delivery.js index 9e7914e..0ab7823 100644 --- a/src/api/routes/delivery.js +++ b/src/api/routes/delivery.js @@ -79,8 +79,11 @@ export function register(app, basePath = '') { * summary: Create delivery * description: | * Creates a goods receipt with header and lines in one transaction. - * Each line requires `sku`, `amount`, `net`, and `tax` (rate). - * `rebate` defaults to `0`; `transactedAmount` defaults to `amount`. + * The manifest `number` is allocated automatically via + * `nextNumber('delivery')`; the user-supplied reference is stored as + * `externalNumber`. Each line requires `sku`, `amount`, `net`, and + * `tax` (rate). `rebate` defaults to `0`; `transactedAmount` defaults + * to `amount`. * security: * - cookieAuth: [] * x-markdown: delivery/create.md @@ -90,10 +93,11 @@ export function register(app, basePath = '') { * application/json: * schema: * type: object - * required: [number, date, lines] + * required: [externalNumber, date, lines] * properties: - * number: + * externalNumber: * type: string + * description: User-supplied reference number * date: * type: string * format: date-time @@ -105,7 +109,7 @@ export function register(app, basePath = '') { * items: * $ref: '#/components/schemas/DeliveryLineInput' * example: - * number: DHL-123 + * externalNumber: DHL-123 * date: '2026-08-10' * supplierId: 1 * lines: @@ -170,11 +174,11 @@ export function register(app, basePath = '') { return res.status(400).json({ error: selected.error }); } - const { number, date, supplierId, lines } = req.body ?? {}; + const { externalNumber, date, supplierId, lines } = req.body ?? {}; try { const delivery = await db.create(req.user.id, { - number, + externalNumber, date, supplierId, lines, @@ -241,8 +245,10 @@ export function register(app, basePath = '') { * tags: [Delivery] * summary: Update delivery * description: | - * Patches header fields that are present. If `lines` is present, replaces - * all lines; if omitted, leaves lines unchanged. Returns the full delivery. + * Patches header fields that are present. The manifest `number` is + * auto-allocated and cannot be patched; only the user-supplied + * `externalNumber` reference is editable. If `lines` is present, + * replaces all lines; if omitted, leaves lines unchanged. * security: * - cookieAuth: [] * x-markdown: delivery/update.md @@ -259,8 +265,10 @@ export function register(app, basePath = '') { * schema: * type: object * properties: - * number: + * externalNumber: * type: string + * nullable: true + * description: User-supplied reference number (empty/null clears it) * date: * type: string * format: date-time @@ -272,7 +280,7 @@ export function register(app, basePath = '') { * items: * $ref: '#/components/schemas/DeliveryLineInput' * example: - * number: DHL-124 + * externalNumber: DHL-124 * lines: [] * responses: * 200: @@ -384,8 +392,8 @@ export function register(app, basePath = '') { const body = req.body ?? {}; const patch = {}; - if (Object.prototype.hasOwnProperty.call(body, 'number')) { - patch.number = body.number; + if (Object.prototype.hasOwnProperty.call(body, 'externalNumber')) { + patch.externalNumber = body.externalNumber; } if (Object.prototype.hasOwnProperty.call(body, 'date')) { patch.date = body.date;