seb/dashback
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Delivery API: use externalNumber for user reference

Browse Source 
Delivery create now accepts externalNumber (user-supplied reference) instead
of number; the manifest number is auto-allocated server-side via
nextNumber('delivery'). Update patches externalNumber (clearable) rather than
number. DeliverySummary schema documents externalNumber and notes number is
auto-generated. Regenerate API docs.
This commit is contained in:
seb
2026-08-08 10:09:32 +02:00
parent 57420ac0db
commit 7514848022
7 changed files with 60 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
docs/api/openapi.json
View File

@@ -4119,7 +4119,7 @@
"Delivery" "Delivery"
], ],
"summary": "Create 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": [ "security": [
{ {
"cookieAuth": [] "cookieAuth": []
@@ -4133,13 +4133,14 @@
"schema": { "schema": {
"type": "object", "type": "object",
"required": [ "required": [
"number", "externalNumber",
"date", "date",
"lines" "lines"
], ],
"properties": { "properties": {
"number": { "externalNumber": {
"type": "string" "type": "string",
"description": "User-supplied reference number"
}, },
"date": { "date": {
"type": "string", "type": "string",
@@ -4157,7 +4158,7 @@
} }
}, },
"example": { "example": {
"number": "DHL-123", "externalNumber": "DHL-123",
"date": "2026-08-10", "date": "2026-08-10",
"supplierId": 1, "supplierId": 1,
"lines": [ "lines": [
@@ -4318,7 +4319,7 @@
"Delivery" "Delivery"
], ],
"summary": "Update 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": [ "security": [
{ {
"cookieAuth": [] "cookieAuth": []
@@ -4342,8 +4343,10 @@
"schema": { "schema": {
"type": "object", "type": "object",
"properties": { "properties": {
"number": { "externalNumber": {
"type": "string" "type": "string",
"nullable": true,
"description": "User-supplied reference number (empty/null clears it)"
}, },
"date": { "date": {
"type": "string", "type": "string",
@@ -4361,7 +4364,7 @@
} }
}, },
"example": { "example": {
"number": "DHL-124", "externalNumber": "DHL-124",
"lines": [] "lines": []
} }
} }
@@ -8804,7 +8807,8 @@
"type": "integer" "type": "integer"
}, },
"number": { "number": {
"type": "string" "type": "string",
"description": "Auto-allocated via nextNumber('delivery')"
}, },
"type": { "type": {
"type": "string", "type": "string",
@@ -8817,6 +8821,11 @@
"nullable": true, "nullable": true,
"description": "manifest.entity_id" "description": "manifest.entity_id"
}, },
"externalNumber": {
"type": "string",
"nullable": true,
"description": "User-supplied reference number"
},
"date": { "date": {
"type": "string", "type": "string",
"format": "date-time" "format": "date-time"

10
docs/api/routes/delivery/create.md
View File

@@ -5,15 +5,18 @@ Protected. Requires a valid session cookie (`credentials: 'include'`).
Create delivery Create delivery
Creates a goods receipt with header and lines in one transaction. Creates a goods receipt with header and lines in one transaction.
Each line requires `sku`, `amount`, `net`, and `tax` (rate). The manifest `number` is allocated automatically via
`rebate` defaults to `0`; `transactedAmount` defaults to `amount`. `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) ## Body (JSON)
```json ```json
{ {
"number": "DHL-123", "externalNumber": "DHL-123",
"date": "2026-08-10", "date": "2026-08-10",
"supplierId": 1, "supplierId": 1,
"lines": [ "lines": [
@@ -38,6 +41,7 @@ Created delivery
"number": "…", "number": "…",
"type": "delivery", "type": "delivery",
"supplierId": 1, "supplierId": 1,
"externalNumber": "…",
"date": "2026-08-10T00:00:00.000Z", "date": "2026-08-10T00:00:00.000Z",
"lines": [ "lines": [
{ {

1
docs/api/routes/delivery/get.md
View File

@@ -23,6 +23,7 @@ Delivery
"number": "…", "number": "…",
"type": "delivery", "type": "delivery",
"supplierId": 1, "supplierId": 1,
"externalNumber": "…",
"date": "2026-08-10T00:00:00.000Z", "date": "2026-08-10T00:00:00.000Z",
"lines": [ "lines": [
{ {

1
docs/api/routes/delivery/list.md
View File

@@ -20,6 +20,7 @@ Delivery list
"number": "…", "number": "…",
"type": "delivery", "type": "delivery",
"supplierId": 1, "supplierId": 1,
"externalNumber": "…",
"date": "2026-08-10T00:00:00.000Z" "date": "2026-08-10T00:00:00.000Z"
} }
] ]

9
docs/api/routes/delivery/update.md
View File

@@ -4,8 +4,10 @@ Protected. Requires a valid session cookie (`credentials: 'include'`).
Update delivery Update delivery
Patches header fields that are present. If `lines` is present, replaces Patches header fields that are present. The manifest `number` is
all lines; if omitted, leaves lines unchanged. Returns the full delivery. 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 ## Path parameters
@@ -18,7 +20,7 @@ all lines; if omitted, leaves lines unchanged. Returns the full delivery.
```json ```json
{ {
"number": "DHL-124", "externalNumber": "DHL-124",
"lines": [] "lines": []
} }
``` ```
@@ -34,6 +36,7 @@ Updated delivery
"number": "…", "number": "…",
"type": "delivery", "type": "delivery",
"supplierId": 1, "supplierId": 1,
"externalNumber": "…",
"date": "2026-08-10T00:00:00.000Z", "date": "2026-08-10T00:00:00.000Z",
"lines": [ "lines": [
{ {

5
src/api/openapi.js
View File

@@ -247,6 +247,7 @@
* type: integer * type: integer
* number: * number:
* type: string * type: string
* description: Auto-allocated via nextNumber('delivery')
* type: * type:
* type: string * type: string
* enum: [delivery] * enum: [delivery]
@@ -254,6 +255,10 @@
* type: integer * type: integer
* nullable: true * nullable: true
* description: manifest.entity_id * description: manifest.entity_id
* externalNumber:
* type: string
* nullable: true
* description: User-supplied reference number
* date: * date:
* type: string * type: string
* format: date-time * format: date-time

34
src/api/routes/delivery.js
View File

@@ -79,8 +79,11 @@ export function register(app, basePath = '') {
* summary: Create delivery * summary: Create delivery
* description: | * description: |
* Creates a goods receipt with header and lines in one transaction. * Creates a goods receipt with header and lines in one transaction.
* Each line requires `sku`, `amount`, `net`, and `tax` (rate). * The manifest `number` is allocated automatically via
* `rebate` defaults to `0`; `transactedAmount` defaults to `amount`. * `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: * security:
* - cookieAuth: [] * - cookieAuth: []
* x-markdown: delivery/create.md * x-markdown: delivery/create.md
@@ -90,10 +93,11 @@ export function register(app, basePath = '') {
* application/json: * application/json:
* schema: * schema:
* type: object * type: object
* required: [number, date, lines] * required: [externalNumber, date, lines]
* properties: * properties:
* number: * externalNumber:
* type: string * type: string
* description: User-supplied reference number
* date: * date:
* type: string * type: string
* format: date-time * format: date-time
@@ -105,7 +109,7 @@ export function register(app, basePath = '') {
* items: * items:
* $ref: '#/components/schemas/DeliveryLineInput' * $ref: '#/components/schemas/DeliveryLineInput'
* example: * example:
* number: DHL-123 * externalNumber: DHL-123
* date: '2026-08-10' * date: '2026-08-10'
* supplierId: 1 * supplierId: 1
* lines: * lines:
@@ -170,11 +174,11 @@ export function register(app, basePath = '') {
return res.status(400).json({ error: selected.error }); return res.status(400).json({ error: selected.error });
} }
const { number, date, supplierId, lines } = req.body ?? {}; const { externalNumber, date, supplierId, lines } = req.body ?? {};
try { try {
const delivery = await db.create(req.user.id, { const delivery = await db.create(req.user.id, {
number, externalNumber,
date, date,
supplierId, supplierId,
lines, lines,
@@ -241,8 +245,10 @@ export function register(app, basePath = '') {
* tags: [Delivery] * tags: [Delivery]
* summary: Update delivery * summary: Update delivery
* description: | * description: |
* Patches header fields that are present. If `lines` is present, replaces * Patches header fields that are present. The manifest `number` is
* all lines; if omitted, leaves lines unchanged. Returns the full delivery. * 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: * security:
* - cookieAuth: [] * - cookieAuth: []
* x-markdown: delivery/update.md * x-markdown: delivery/update.md
@@ -259,8 +265,10 @@ export function register(app, basePath = '') {
* schema: * schema:
* type: object * type: object
* properties: * properties:
* number: * externalNumber:
* type: string * type: string
* nullable: true
* description: User-supplied reference number (empty/null clears it)
* date: * date:
* type: string * type: string
* format: date-time * format: date-time
@@ -272,7 +280,7 @@ export function register(app, basePath = '') {
* items: * items:
* $ref: '#/components/schemas/DeliveryLineInput' * $ref: '#/components/schemas/DeliveryLineInput'
* example: * example:
* number: DHL-124 * externalNumber: DHL-124
* lines: [] * lines: []
* responses: * responses:
* 200: * 200:
@@ -384,8 +392,8 @@ export function register(app, basePath = '') {
const body = req.body ?? {}; const body = req.body ?? {};
const patch = {}; const patch = {};
if (Object.prototype.hasOwnProperty.call(body, 'number')) { if (Object.prototype.hasOwnProperty.call(body, 'externalNumber')) {
patch.number = body.number; patch.externalNumber = body.externalNumber;
} }
if (Object.prototype.hasOwnProperty.call(body, 'date')) { if (Object.prototype.hasOwnProperty.call(body, 'date')) {
patch.date = body.date; patch.date = body.date;