dashback/docs/api

Dash API

http://localhost:4208/api
https://localhost:8443/api
https://localhost:8443/v1  (POS API)

CORS & cookies

All browser requests that need auth must send cookies:

fetch('http://localhost:4208/api/auth/me', {
  credentials: 'include',
});

Sessions use an HTTP-only token cookie (Secure, SameSite=Strict, 24h). The browser must talk to the API over HTTPS for login to work — Secure cookies are not sent on plain HTTP.

Auth flow

1. Call GET /auth/me to get googleClientId (included in 200 and 401 responses).
2. Sign in with Google on the frontend (Google Identity Services / One Tap).
3. POST the Google ID token to POST /auth/login.
4. The API sets the session cookie.
5. Call protected routes with credentials: 'include'. The cookie is refreshed automatically when it has less than 2 hours left.

Routes

Generated from @openapi annotations in src/api/routes/. Source of truth is the code; regenerate with npm run docs:api.

File	Endpoint
routes/.well-known/oauth-authorization-server.md	GET /.well-known/oauth-authorization-server
routes/.well-known/oauth-protected-resource.md	GET /.well-known/oauth-protected-resource
routes/account.get.md	GET /account
routes/account.post.md	POST /account
routes/account/_id.md	DELETE /account/{id}
routes/article/create.md	POST /article
routes/article/export.zip.md	GET /article/export.zip
routes/article/history-list.md	GET /article/history
routes/article/delete.md	DELETE /article/{sku}
routes/article/get.md	GET /article/{sku}
routes/article/update.md	PATCH /article/{sku}
routes/article/_sku/articlelist.get.md	GET /article/{sku}/articlelist
routes/article/_sku/articlelist.put.md	PUT /article/{sku}/articlelist
routes/article/_sku/attributevalue.get.md	GET /article/{sku}/attributevalue
routes/article/_sku/attributevalue.put.md	PUT /article/{sku}/attributevalue
routes/article/set-brand.md	PUT /article/{sku}/brand
routes/article/set-categories.md	PUT /article/{sku}/categories
routes/article/_sku/children.get.md	GET /article/{sku}/children
routes/article/_sku/children.post.md	POST /article/{sku}/children
routes/article/_sku/children.put.md	PUT /article/{sku}/children
routes/article/_sku/children/_childSku.md	DELETE /article/{sku}/children/{childSku}
routes/article/set-eans.md	PUT /article/{sku}/eans
routes/article/history.md	GET /article/{sku}/history
routes/article/add-image.md	POST /article/{sku}/image
routes/article/delete-image.md	DELETE /article/{sku}/image/{fullHash}
routes/article/order-images.md	PUT /article/{sku}/images/order
routes/article/_sku/optionslist.get.md	GET /article/{sku}/optionslist
routes/article/_sku/optionslist.put.md	PUT /article/{sku}/optionslist
routes/article/_sku/parent.md	POST /article/{sku}/parent
routes/article/set-prices.md	PUT /article/{sku}/prices
routes/article/_sku/print.md	POST /article/{sku}/print
routes/article/_sku/property.get.md	GET /article/{sku}/property
routes/article/_sku/property.put.md	PUT /article/{sku}/property
routes/article/_sku/property/_propertyId.md	DELETE /article/{sku}/property/{propertyId}
routes/article/supplier/list.md	GET /article/{sku}/supplier
routes/article/supplier/create.md	POST /article/{sku}/supplier
routes/article/supplier/order.md	PUT /article/{sku}/supplier/order
routes/article/supplier/delete.md	DELETE /article/{sku}/supplier/{id}
routes/article/supplier/update.md	PATCH /article/{sku}/supplier/{id}
routes/article/_sku/track_stock.md	PUT /article/{sku}/track_stock
routes/article/set-weight.md	PUT /article/{sku}/weight
routes/attributename.get.md	GET /attributename
routes/attributename.post.md	POST /attributename
routes/attributename/order.md	PUT /attributename/order
routes/attributename/_attributeId/value.get.md	GET /attributename/{attributeId}/value
routes/attributename/_attributeId/value.post.md	POST /attributename/{attributeId}/value
routes/attributename/_attributeId/value/order.md	PUT /attributename/{attributeId}/value/order
routes/attributename/_id.delete.md	DELETE /attributename/{id}
routes/attributename/_id.patch.md	PATCH /attributename/{id}
routes/attributevalue/_id.delete.md	DELETE /attributevalue/{id}
routes/attributevalue/_id.patch.md	PATCH /attributevalue/{id}
routes/attributevalue/_id/image.delete.md	DELETE /attributevalue/{id}/image
routes/attributevalue/_id/image.post.md	POST /attributevalue/{id}/image
routes/auth/login.md	POST /auth/login
routes/auth/logout.md	POST /auth/logout
routes/auth/me.md	GET /auth/me
routes/auth/selected-company.md	PUT /auth/selected-company
routes/backup.md	GET /backup
routes/backup/_id/vfs.md	GET /backup/{id}/vfs
routes/backup/_id/vfs/recover.md	POST /backup/{id}/vfs/recover
routes/brand/list.md	GET /brand
routes/brand/create.md	POST /brand
routes/brand/delete.md	DELETE /brand/{id}
routes/brand/update.md	PATCH /brand/{id}
routes/brand/_id/image.delete.md	DELETE /brand/{id}/image
routes/brand/_id/image.post.md	POST /brand/{id}/image
routes/carrier.get.md	GET /carrier
routes/carrier.post.md	POST /carrier
routes/carrier/order.md	PUT /carrier/order
routes/carrier/_id.delete.md	DELETE /carrier/{id}
routes/carrier/_id.get.md	GET /carrier/{id}
routes/carrier/_id.patch.md	PATCH /carrier/{id}
routes/category/create.md	POST /category
routes/category/export.zip.md	GET /category/export.zip
routes/category/order.md	PUT /category/order
routes/category/tree.md	GET /category/tree
routes/category/delete.md	DELETE /category/{id}
routes/category/update.md	PATCH /category/{id}
routes/category/articles.md	GET /category/{id}/articles
routes/category/_id/attributevalue.get.md	GET /category/{id}/attributevalue
routes/category/_id/attributevalue.put.md	PUT /category/{id}/attributevalue
routes/category/delete-image.md	DELETE /category/{id}/image
routes/category/add-image.md	POST /category/{id}/image
routes/category/_id/property.get.md	GET /category/{id}/property
routes/category/_id/property.put.md	PUT /category/{id}/property
routes/category/_id/property/_propertyId.md	DELETE /category/{id}/property/{propertyId}
routes/company/list.md	GET /company
routes/company/create.md	POST /company
routes/company/export.md	GET /company/export
routes/company/export.post.md	POST /company/export
routes/company/history.md	GET /company/history
routes/company/addHistory.md	POST /company/history
routes/company/import.md	POST /company/import
routes/companysetting/list.md	GET /company/setting
routes/companysetting/get.md	GET /company/setting/{key}
routes/companysetting/set.md	PUT /company/setting/{key}
routes/company/delete.md	DELETE /company/{id}
routes/company/update.md	PUT /company/{id}
routes/customergroup/list.md	GET /customergroup
routes/customergroup/create.md	POST /customergroup
routes/customergroup/order.md	PUT /customergroup/order
routes/customergroup/delete.md	DELETE /customergroup/{id}
routes/customergroup/update.md	PATCH /customergroup/{id}
routes/delivery/list.md	GET /delivery
routes/delivery/create.md	POST /delivery
routes/delivery/delete.md	DELETE /delivery/{id}
routes/delivery/get.md	GET /delivery/{id}
routes/delivery/update.md	PATCH /delivery/{id}
routes/delivery/_id/file/_fileId.delete.md	DELETE /delivery/{id}/file/{fileId}
routes/delivery/file.md	GET /delivery/{id}/file/{fileId}
routes/delivery/_id/pdf.md	POST /delivery/{id}/pdf
routes/entity/list.md	GET /entity
routes/entity/create.md	POST /entity
routes/entity/next-number.md	GET /entity/next-number
routes/entity/address/list.md	GET /entity/{entityId}/address
routes/entity/address/create.md	POST /entity/{entityId}/address
routes/entity/address/delete.md	DELETE /entity/{entityId}/address/{id}
routes/entity/address/update.md	PATCH /entity/{entityId}/address/{id}
routes/entity/contact/list.md	GET /entity/{entityId}/contact
routes/entity/contact/create.md	POST /entity/{entityId}/contact
routes/entity/contact/delete.md	DELETE /entity/{entityId}/contact/{id}
routes/entity/contact/update.md	PATCH /entity/{entityId}/contact/{id}
routes/entity/delete.md	DELETE /entity/{id}
routes/entity/get.md	GET /entity/{id}
routes/entity/update.md	PATCH /entity/{id}
routes/events.md	GET /events
routes/health.md	GET /health
routes/health/latency.md	GET /health/latency
routes/image/get.md	GET /image/{fullHash}
routes/labeltemplate/list.md	GET /labeltemplate
routes/labeltemplate/create.md	POST /labeltemplate
routes/labeltemplate/delete.md	DELETE /labeltemplate/{id}
routes/labeltemplate/get.md	GET /labeltemplate/{id}
routes/labeltemplate/update.md	PATCH /labeltemplate/{id}
routes/labeltemplate/update.md	PUT /labeltemplate/{id}
routes/ledger.md	GET /ledger
routes/ledger/history.md	GET /ledger/history
routes/ledger/manifestarticle/_manifestarticleId.md	GET /ledger/manifestarticle/{manifestarticleId}
routes/ledger/sku/_sku.md	GET /ledger/sku/{sku}
routes/mcp.md	POST /mcp
routes/mcp/authorizations.md	GET /mcp/authorizations
routes/mcp/authorizations/_clientId.md	DELETE /mcp/authorizations/{clientId}
routes/mcp/authorize.get.md	GET /mcp/authorize
routes/mcp/authorize.post.md	POST /mcp/authorize
routes/mcp/clients.md	GET /mcp/clients
routes/mcp/clients/_clientId.md	DELETE /mcp/clients/{clientId}
routes/modelconversation.get.md	GET /modelconversation
routes/modelconversation.post.md	POST /modelconversation
routes/modelconversation/_id.delete.md	DELETE /modelconversation/{id}
routes/modelconversation/_id.get.md	GET /modelconversation/{id}
routes/modelconversation/_id/message.get.md	GET /modelconversation/{id}/message
routes/modelconversation/_id/message.post.md	POST /modelconversation/{id}/message
routes/modelconversation/_id/stream.md	GET /modelconversation/{id}/stream
routes/number/list.md	GET /number
routes/number/update.md	PATCH /number/{id}
routes/oauth/authorize.md	GET /oauth/authorize
routes/oauth/introspect.md	POST /oauth/introspect
routes/oauth/register.md	POST /oauth/register
routes/oauth/token.md	POST /oauth/token
routes/order/list.md	GET /order
routes/order/create.md	POST /order
routes/order/delete.md	DELETE /order/{id}
routes/order/get.md	GET /order/{id}
routes/order/update.md	PATCH /order/{id}
routes/order/_id/file/_fileId.delete.md	DELETE /order/{id}/file/{fileId}
routes/order/_id/file/_fileId.get.md	GET /order/{id}/file/{fileId}
routes/order/_id/payment.get.md	GET /order/{id}/payment
routes/order/_id/payment.post.md	POST /order/{id}/payment
routes/order/_id/pdf.md	POST /order/{id}/pdf
routes/order/_id/shipment.get.md	GET /order/{id}/shipment
routes/order/_id/shipment.post.md	POST /order/{id}/shipment
routes/order/_id/shipping.get.md	GET /order/{id}/shipping
routes/order/_id/shipping.post.md	POST /order/{id}/shipping
routes/package/_id.md	DELETE /package/{id}
routes/payment/_id.md	DELETE /payment/{id}
routes/posterminal/list.md	GET /posterminal
routes/posterminal/upsert.md	PUT /posterminal
routes/posterminal/delete.md	DELETE /posterminal/{id}
routes/posterminal/update.md	PATCH /posterminal/{id}
routes/posterminal/setOffAll.md	DELETE /posterminal/{id}/all
routes/posterminal/setOnAll.md	PUT /posterminal/{id}/all
routes/posterminal/setOff.md	DELETE /posterminal/{id}/category/{categoryId}
routes/posterminal/setOn.md	PUT /posterminal/{id}/category/{categoryId}
routes/printer/list.md	GET /printer
routes/printer/create.md	POST /printer
routes/printer/order.md	PUT /printer/order
routes/printer/delete.md	DELETE /printer/{id}
routes/printer/get.md	GET /printer/{id}
routes/printer/update.md	PATCH /printer/{id}
routes/printer/_id.put.md	PUT /printer/{id}
routes/propertyname.get.md	GET /propertyname
routes/propertyname.post.md	POST /propertyname
routes/propertyname/order.md	PUT /propertyname/order
routes/propertyname/_id.delete.md	DELETE /propertyname/{id}
routes/propertyname/_id.patch.md	PATCH /propertyname/{id}
routes/public/telemetry/crash.md	POST /public/telemetry/crash
routes/public/_companyId/articles.md	GET /public/{companyId}/articles
routes/public/_companyId/articles/_sku.md	GET /public/{companyId}/articles/{sku}
routes/public/_companyId/categories.md	GET /public/{companyId}/categories
routes/quote/list.md	GET /quote
routes/quote/create.md	POST /quote
routes/quote/delete.md	DELETE /quote/{id}
routes/quote/get.md	GET /quote/{id}
routes/quote/update.md	PATCH /quote/{id}
routes/quote/_id/file/_fileId.delete.md	DELETE /quote/{id}/file/{fileId}
routes/quote/_id/file/_fileId.get.md	GET /quote/{id}/file/{fileId}
routes/quote/order.md	POST /quote/{id}/order
routes/quote/_id/pdf.md	POST /quote/{id}/pdf
routes/serper/image.md	POST /serper/image
routes/serper/images.md	POST /serper/images
routes/shipment/_id.delete.md	DELETE /shipment/{id}
routes/shipment/_id.get.md	GET /shipment/{id}
routes/shipment/_id.patch.md	PATCH /shipment/{id}
routes/shipment/_id/file/_fileId.delete.md	DELETE /shipment/{id}/file/{fileId}
routes/shipment/_id/file/_fileId.get.md	GET /shipment/{id}/file/{fileId}
routes/shipment/_id/pdf.md	POST /shipment/{id}/pdf
routes/shipment/_id/shipping.get.md	GET /shipment/{id}/shipping
routes/shipment/_id/shipping.post.md	POST /shipment/{id}/shipping
routes/shipping/_id.delete.md	DELETE /shipping/{id}
routes/shipping/_id.patch.md	PATCH /shipping/{id}
routes/shipping/_id/package.get.md	GET /shipping/{id}/package
routes/shipping/_id/package.post.md	POST /shipping/{id}/package
routes/smallthumb/get.md	GET /smallthumb/{fullHash}
routes/stock/accept.md	POST /stock/accept
routes/stock/adjust.md	POST /stock/adjust
routes/stock/ship.md	POST /stock/ship
routes/subagentschedule.get.md	GET /subagentschedule
routes/subagentschedule.post.md	POST /subagentschedule
routes/subagentschedule/_id.delete.md	DELETE /subagentschedule/{id}
routes/subagentschedule/_id.get.md	GET /subagentschedule/{id}
routes/subagentschedule/_id.put.md	PUT /subagentschedule/{id}
routes/supplier/list.md	GET /supplier
routes/supplier/create.md	POST /supplier
routes/supplier/delete.md	DELETE /supplier/{id}
routes/supplier/update.md	PATCH /supplier/{id}
routes/supplier/articles.get.md	GET /supplier/{id}/articles
routes/supplier/articles.post.md	POST /supplier/{id}/articles
routes/thumb/get.md	GET /thumb/{fullHash}
routes/unit/delete.md	DELETE /unit
routes/unit/list.md	GET /unit
routes/unit/upsert.md	PUT /unit
routes/v1/category.md	GET /v1/category
routes/pos/client.md	GET /v1/client
routes/pos/init.md	GET /v1/init
routes/pos/pimage.md	GET /v1/pimage
routes/v1/product.md	GET /v1/product
routes/vfs/list.md	GET /vfs
routes/vfs/applets-restore.md	POST /vfs/applets/restore
routes/vfs/mkdir.md	POST /vfs/mkdir
routes/vfs/rename.md	POST /vfs/rename
routes/vfs/skills-restore.md	POST /vfs/skills/restore
routes/vfs/upload.md	POST /vfs/upload
routes/vfs/delete.md	DELETE /vfs/{*path}
routes/vfs/_*path.md	GET /vfs/{*path}
routes/vfs/exec.md	POST /vfs/{*path}
routes/vfs/write.md	PUT /vfs/{*path}
routes/warehouse/list.md	GET /warehouse
routes/warehouse/create.md	POST /warehouse
routes/warehouse/order.md	PUT /warehouse/order
routes/warehouse/delete.md	DELETE /warehouse/{id}
routes/warehouse/get.md	GET /warehouse/{id}
routes/warehouse/update.md	PATCH /warehouse/{id}
routes/warehouse/_id.put.md	PUT /warehouse/{id}

Route overview: routes.md | All routes: routes-all.md.

Signals (SSE)

Clients subscribe via GET /events (text/event-stream). After a successful mutation, the API emits a named SSE event (signal) to subscribers of the same selected company.

Signal	Emitted by
article-<sku>	PUT /article/{sku}/brand, PUT /article/{sku}/categories, PUT /article/{sku}/eans, POST /article/{sku}/image, DELETE /article/{sku}/image/{fullHash}, PUT /article/{sku}/images/order, PUT /article/{sku}/prices, POST /article/{sku}/supplier, PUT /article/{sku}/supplier/order, DELETE /article/{sku}/supplier/{id}, PATCH /article/{sku}/supplier/{id}, PUT /article/{sku}/track_stock, PUT /article/{sku}/weight, POST /stock/adjust
articles	POST /article, DELETE /article/{sku}, PATCH /article/{sku}, DELETE /category/{id}, POST /stock/accept, POST /stock/adjust, POST /stock/ship
attributename	POST /attributename, PUT /attributename/order, DELETE /attributename/{id}, PATCH /attributename/{id}, DELETE /attributevalue/{id}/image, POST /attributevalue/{id}/image
brand	POST /brand, DELETE /brand/{id}, PATCH /brand/{id}, DELETE /brand/{id}/image, POST /brand/{id}/image
carrier	POST /carrier, PUT /carrier/order, DELETE /carrier/{id}, PATCH /carrier/{id}
category	POST /category, PUT /category/order, DELETE /category/{id}, PATCH /category/{id}, DELETE /category/{id}/image, POST /category/{id}/image
delivery	DELETE /delivery/{id}/file/{fileId}, POST /delivery/{id}/pdf, POST /stock/accept
labeltemplate	POST /labeltemplate, DELETE /labeltemplate/{id}, PATCH /labeltemplate/{id}, PUT /labeltemplate/{id}
ledger	POST /stock/accept, POST /stock/adjust, POST /stock/ship
modelconversation	POST /modelconversation, DELETE /modelconversation/{id}
modelconversation-<id>	POST /modelconversation/{id}/message
order	DELETE /order/{id}/file/{fileId}, POST /order/{id}/pdf, PATCH /shipment/{id}, DELETE /shipment/{id}/file/{fileId}
printer	POST /printer, PUT /printer/order, DELETE /printer/{id}, PATCH /printer/{id}, PUT /printer/{id}
propertyname	POST /propertyname, PUT /propertyname/order, DELETE /propertyname/{id}, PATCH /propertyname/{id}
quote	DELETE /quote/{id}/file/{fileId}, POST /quote/{id}/pdf
shipment	PATCH /shipment/{id}, DELETE /shipment/{id}/file/{fileId}, POST /shipment/{id}/pdf
shipping	POST /stock/ship
stock	POST /stock/accept, POST /stock/adjust, POST /stock/ship
subagentschedule	POST /subagentschedule, DELETE /subagentschedule/{id}, PUT /subagentschedule/{id}
vfs	POST /vfs/applets/restore, POST /vfs/mkdir, POST /vfs/rename, POST /vfs/skills/restore, POST /vfs/upload, DELETE /vfs/{*path}, POST /vfs/{*path}, PUT /vfs/{*path}
warehouse	POST /warehouse, PUT /warehouse/order, DELETE /warehouse/{id}, PUT /warehouse/{id}

DESIGN

• for every route we have a file in /src/api/routes
• that should loosly bound to services in /src/services
• for every service we have a CLI tester in /scripts/
• all DB SQL code shall be in /src/db
• with SQL staements in /src/db/
• API docs: @openapi JSDoc on handlers → npm run docs:api → docs/api/