Document Service

Back

Note: The sales order model has been replaced by the generic Document model. All endpoints are now under /api/v1/Documents. The document approach supports multiple document types (sales orders, credit notes, quotes, etc.) through the DocumentTypeId field.

Overview

Documents represent transactional records — sales orders, credit notes, quotes, and any other document type defined in ref.DocumentType.

Documents provide a consistent reference for:

• recording and processing customer orders
• tracking status, fulfillment, and dispatch
• stamping immutable billing and shipping address snapshots at creation time
• attaching line items, files, and time entries
• reporting and analytics

Soft delete is supported — deleted documents have IsDeleted = true and a DeletedAt timestamp rather than being physically removed.

All document operations are tenant-aware.

Database tables

• sales.Document
• sales.DocumentLine
• sales.DocumentAddressSnapshot
• ref.DocumentType
• ref.DocumentCategory

Endpoints

Back to Sales

GET

/api/v1/Documents

Returns a paginated, filterable list of documents.

Query parameters (pagination):

• page (int, default: 1) — page number (1-based)
• pageSize (int, default: 20, max: 100) — items per page. Pass 0 to receive only totalCount with an empty items array
• sortBy (string, optional) — field to sort by: ordernumber, orderdate, grandtotal, createdat
• sortDesc (bool, default: false) — sort descending

Query parameters (filters):

• search (string, optional) — search across order number and courier reference
• entityId (long, optional) — filter by customer/entity ID
• documentTypeId (int, optional) — filter by document type
• isComplete (bool, optional) — filter by completion status
• orderDate (yyyy-MM-dd, optional) — filter by exact order date; ignored when dateFrom/dateTo are used

Query parameters (date window):

• dateFrom (yyyy-MM-dd, optional) — start of date range, inclusive
• dateTo (yyyy-MM-dd, optional) — end of date range, inclusive
• dateProperty (string, default: "orderdate") — column to filter on: "orderdate" or "createdat"

Example — all documents for entity 5 in April 2026:

GET /api/v1/Documents?entityId=5&dateFrom=2026-04-01&dateTo=2026-04-30&dateProperty=orderdate&pageSize=0

Response:

• PagedResponse<DocumentModel>

Authorization:

• Requires Bearer Token
• Permission: OrdersRead

GET

/api/v1/Documents/{id}

Returns a single document by its numeric identifier, including all lines.

Route parameters:

• id (long, required) — document identifier

Behavior:

• Returns 404 if not found

Response:

• DocumentModel (includes Lines list)

Authorization:

• Requires Bearer Token
• Permission: OrdersRead

GET

/api/v1/Documents/ref/{orderNumber}/entity/{entityId}

Returns a document matching both order reference and entity ID.

Route parameters:

• orderNumber (string, required) — order reference number
• entityId (long, required) — entity identifier

Behavior:

• Returns 404 if no match found

Response:

• DocumentModel

Authorization:

• Requires Bearer Token
• Permission: FullRead

GET

/api/v1/Documents/{id}/files

Returns a paginated list of file attachments linked to a document.

Route parameters:

• id (long, required) — document identifier

Query parameters: see FileFilterRequest (standard pagination + search)

Response:

• PagedResponse<FileMetadataModel>

Authorization:

• Requires Bearer Token

POST

/api/v1/Documents

Creates a new document.

Request body (DocumentModel):

• See Document Model for full field reference
• OrderNumber, EntityId, OrderDate, Currency, DocumentTypeId, GrandTotal >= 0 are required
• StatusId is not part of the request — the initial status is always derived from the document type's InitialStatusGuid (falls back to NEW_ORDER), never supplied by the caller

Behavior:

• Validation is handled in the service layer
• Successful creation writes an audit log entry

Response:

• 201 Created — DocumentModel

Authorization:

• Requires Bearer Token
• Permission: OrdersWrite

POST

/api/v1/Documents/{id}/convert

Converts or clones an existing document into a different document type.

Route parameters:

• id (long, required) — source document identifier

Query parameters:

• documentTypeGuid (string, required) — target document type code (e.g. "SALES_ORDER", "QUOTE")
• clone (bool, default: false) — if false, updates the existing document in place; if true, creates a new document copy and leaves the original unchanged

Behavior:

• Validates the conversion is actually allowed from the source document's current type/status (via DocumentActionEngine) — returns 409 (DocumentConversionNotAllowed) if not
• Resolves the target document type by documentTypeGuid
• The resulting document status is always derived from the target type's InitialStatusGuid configuration; falls back to NEW_ORDER if not set
• When clone=false the same document record is updated and returned
• When clone=true a new document with its own order number is created; the original remains unchanged, unless the matching conversion action defines a post-conversion status for the source (e.g. a Sales Order converted to an Invoice moves the source Sales Order to COMPLETED)

Response:

• 200 OK — DocumentModel

Authorization:

• Requires Bearer Token
• Permission: DocumentsWrite

POST

/api/v1/Documents/{id}/actions/{actionCode}

Performs a lifecycle action on a document (e.g. BEGIN_PROCESSING, CANCEL, EMAIL_DOCUMENT_SUMMARY). This is the only way a document's status changes outside of creation/conversion — the caller names the action, not the destination status, and the server resolves the actual result (which may depend on live stock levels or tenant feature flags). See DocumentModel.DocumentActionState.AllowedActions for what's currently invokable on a given document.

Route parameters:

• id (long, required) — document identifier
• actionCode (string, required) — e.g. BEGIN_PROCESSING, CANCEL, MARK_DISPATCHED, ISSUE, MARK_PAID, CONVERT_TO_SALES_ORDER, CONVERT_TO_INVOICE, EMAIL_PAYMENT_REMINDER, EMAIL_DOCUMENT_SUMMARY

Behavior:

• Returns 404 (DocumentActionNotFound) if actionCode isn't a recognised action
• Returns 409 (DocumentActionNotAllowed) if the action isn't currently valid for the document's status
• Returns 409 (DocumentActionRequiresOrderLines) for BEGIN_PROCESSING if the Sales Order has no order lines
• CONVERT_TO_* actions delegate into the same conversion logic as POST {id}/convert, per-action: CONVERT_TO_SALES_ORDER transforms a Quote into the same document in place (clone=false — it becomes the Sales Order, it isn't cloned into one); CONVERT_TO_INVOICE clones the Sales Order into a new Invoice document (clone=true) and also moves the source Sales Order to COMPLETED, only invokable while the Sales Order is READY_TO_INVOICE
• EMAIL_PAYMENT_REMINDER/EMAIL_DOCUMENT_SUMMARY are pure side effects (delegate to the same logic as POST {id}/email?type=PaymentReminder|Document) — the document's status is unchanged
• Otherwise resolves and applies the resulting status (and any associated date field, e.g. CANCEL sets CancelledDate)
• There is no document-level "mark picked" action — picking happens per line via POST /api/v1/DocumentLines/{id}/pick, which automatically resolves the document's next status once every line is picked

Response:

• 200 OK — DocumentModel

Authorization:

• Requires Bearer Token
• Permission: DocumentsWrite

POST

/api/v1/Documents/PurchaseOrders

Generates Purchase Orders from Sales Orders that have lines with insufficient stock.

Behavior:

• Scans all Sales Order documents in NEW_ORDER or PROCESS_AWAITINGSTOCK status
• For each line where Quantity > stock on hand, calculates the shortfall
• Groups shortfalls by supplier entity; creates one PO per supplier or adds lines to an existing open PO (status: NEW_ORDER) for that supplier
• Copies UnitPrice and TaxRate from the originating Sales Order line
• Recalculates PO totals after all lines are added
• Returns a summary of the operation

Response:

• 200 OK — GeneratePurchaseOrdersResult

Authorization:

• Requires Bearer Token
• Permission: DocumentsWrite

POST

/api/v1/Documents/{documentId}/files/assign

Assigns one or more existing files to a document.

Route parameters:

• documentId (long, required)

Request body (FileIdsRequest):

• FileIds (List, required)

Response:

• 204 No Content

Authorization:

• Requires Bearer Token
• Permission: FullManage

PUT

/api/v1/Documents/{id}

Updates an existing document.

Route parameters:

• id (int, required) — document identifier

Request body (DocumentModel):

• Id is set from the route
• Id > 0, EntityId > 0, DocumentTypeId > 0 are required
• StatusId and the status-linked date fields (CancelledDate, DispatchDate, CustomisationDate, CompletedDate, InProgressDate, PaidDate) are not part of the request — they only ever change as a side effect of POST {id}/actions/{actionCode}

Behavior:

• Updates all provided fields (excluding status/status-linked dates — see above)
• Successful update writes an audit log entry

Response:

• 200 OK — DocumentModel

Authorization:

• Requires Bearer Token
• Permission: OrdersWrite

DELETE

/api/v1/Documents/{id}

Soft-deletes a document.

Route parameters:

• id (long, required) — document identifier

Behavior:

• Sets IsDeleted = true and DeletedAt to current UTC time
• Record is retained in the database
• Successful deletion writes an audit log entry

Response:

• 204 No Content

Authorization:

• Requires Bearer Token
• Permission: FullManage

DELETE

/api/v1/Documents/{documentId}/files/remove

Removes one or more file associations from a document (does not delete the file itself).

Route parameters:

• documentId (long, required)

Request body (FileIdsRequest):

• FileIds (List, required)

Response:

• 204 No Content

Authorization:

• Requires Bearer Token
• Permission: FullManage

Models

DocumentModel

Represents a document (sales order, credit note, quote, etc.).

Fields:

• Id (type: long) — internal identifier
• OrderNumber (type: string?) — order reference number
• EntityId (type: long?) — customer entity identifier
• UserId (type: long?) — user who created the document
• StatusId (type: int) — order status; read-only — always derived from the document type on creation/conversion, or resolved by an action (see DocumentActionState.AllowedActions), never caller-supplied
• OrderDate (type: DateTime?) — order creation date
• Currency (type: string?) — order currency
• BillingDocumentAddressSnapshotId (type: long?) — FK to billing address snapshot
• ShippingDocumentAddressSnapshotId (type: long?) — FK to shipping address snapshot
• PriceListId (type: long?) — price list applied
• Subtotal (type: decimal?) — subtotal amount
• TaxTotal (type: decimal?) — tax total
• ShippingTotal (type: decimal?) — shipping total
• GrandTotal (type: decimal?) — final total
• Notes (type: string?) — order notes
• CreatedAt (type: DateTime?) — creation timestamp
• DueDate (type: DateTime?) — payment due date
• PromotionId (type: int?) — applied promotion
• PaidDate (type: DateTime?) — payment date
• CompletedDate (type: DateTime?) — completion date
• DispatchDate (type: DateTime?) — dispatch/shipping date
• Courier (type: string?) — courier name
• CourierRef (type: string?) — courier reference number
• DocumentTypeId (type: int?) — document type FK
• InProgressDate (type: DateTime?) — date moved to in-progress
• PurchaseOrderRef (type: string?) — customer PO reference
• AdditionalRef (type: string?) — secondary reference
• DocumentCategoryId (type: int?) — document category FK
• Tags (type: string?) — comma-separated tags
• Description (type: string?) — document description
• ActionNotes (type: string?) — internal action notes
• Other1 (type: string?) — configurable field 1
• Other2 (type: string?) — configurable field 2
• Other3 (type: string?) — configurable field 3
• OtherNotes (type: string?) — additional notes
• Lines (type: List<DocumentLineModel>?) — line items (populated on read, ordered by LineNumber)
• Status (type: OrderStatus?) — resolved status object
• DocumentType (type: DocumentTypeModel?) — resolved document type object
• Entity (type: EntityModel?) — resolved entity object
• DocumentCategory (type: DocumentCategoryModel?) — resolved category object
• BillingAddress (type: DocumentAddressSnapshotModel?) — immutable billing address snapshot
• ShippingAddress (type: DocumentAddressSnapshotModel?) — immutable shipping address snapshot
• DocumentActionState (type: DocumentActionState?) — the full computed action/permission state for this document's current type/status, as returned by DocumentActionEngine.GetDocumentActionState:
  • IsValid (type: bool) — false if the document has no type/status or no action configuration exists for its type; Errors explains why
  • Errors (type: IReadOnlyList<string>) — populated only when IsValid is false
  • AllowedActions (type: IReadOnlyList<DocumentActionDescriptor>) — what the caller can currently do to this document (Code, Label, Trigger); the primary contract for driving action buttons. Invoke via POST {id}/actions/{Code}
  • FieldPermissions (type: DocumentStatusFieldPermissions) — which of the date fields above are ever relevant to show for this document's current type/status (one bool per date field: OrderDate, PaidDate, CompletedDate, DispatchDate, InProgressDate, DueDate, CustomisationDate, CancelledDate, QuoteDate, InvoicedDate). This is a status-driven permission, not a "has a value" check — the frontend should only display a date field when its flag here is true AND the field itself is non-null. Computed by DocumentActionEngine, e.g. a Sales Order only exposes CompletedDate/DispatchDate once it reaches AWAITING_PICK/AWAITING_STOCK, and CustomisationDate additionally requires the tenant to have the document:customisation feature
  • HasFinancialDetails (type: bool) — whether this document type carries financial details (subtotal/tax/grand total) worth showing; currently only true for Invoices
  • HasManpackDetails (type: bool), HasStockDetails (type: bool), HasCustomisationDetails (type: bool) — whether manpacking/stock/customisation details are relevant for this document's current type/status
  • CanViewEntireCatalog (type: bool) — whether this document's type is exempt from the entity's product allow-list (currently true only for Quotes and Purchase Orders); informs the frontend whether to scope product pickers to the entity's allowed products or show the full catalogue
  • FullyPicked (type: bool) — whether all stock-required lines are picked

Validation:

• IsReadyToAdd() — requires EntityId, OrderNumber, OrderDate, Currency, DocumentTypeId, GrandTotal >= 0
• IsReadyToUpdate() — requires Id > 0, EntityId > 0, DocumentTypeId > 0

DocumentLineModel

Represents a single line item within a document.

Fields:

• Id (type: long?) — internal identifier
• DocumentId (type: long?) — parent document
• LineNumber (type: int?) — line sequence number
• ProductId (type: long?) — product identifier
• ProductVariantId (type: long?) — product variant identifier
• Sku (type: string?) — product SKU at time of order
• Title (type: string?) — product title at time of order
• Description (type: string?) — line description
• Quantity (type: decimal?) — quantity ordered
• UnitPrice (type: decimal?) — price per unit
• DefaultSalePrice (type: decimal?) — catalogue price before any override
• DiscountAmount (type: decimal?) — discount applied
• TaxRate (type: decimal?) — tax rate applied
• TaxAmount (type: decimal?) — tax amount
• LineTotal (type: decimal?) — line total after discounts and tax
• WarehouseId (type: long?) — warehouse the goods are allocated from
• EntityUserId (type: long?) — user who created the line
• Notes (type: string?) — additional notes
• QuantityFulfilled (type: decimal?) — fulfilled quantity
• QuantityReturned (type: decimal?) — returned quantity
• ReturnedDate (type: DateTime?) — date of return

Validation:

• IsReadyToAdd() — requires DocumentId, LineNumber, ProductId, Quantity > 0, UnitPrice >= 0, LineTotal >= 0
• IsReadyToUpdate() — requires Id > 0, DocumentId > 0, ProductId > 0, Quantity >= 0, UnitPrice >= 0

GeneratePurchaseOrdersResult

Returned by POST /api/v1/Documents/PurchaseOrders.

Fields:

• PurchaseOrdersCreated (type: int) — number of new PO documents created
• PurchaseOrdersUpdated (type: int) — number of existing PO documents that had lines added
• LinesAdded (type: int) — total number of PO lines inserted

DocumentAddressSnapshotModel

An immutable copy of an address stamped at the time the document was created (via cart convert or manual creation).

Fields:

• Id (type: long) — internal identifier
• Name (type: string?) — address name / company
• Line1 (type: string?) — street address line 1
• Line2 (type: string?) — street address line 2
• City (type: string?) — city
• StateRegion (type: string?) — state or region
• PostalCode (type: string?) — postal/ZIP code
• CountryCode (type: string?) — ISO country code
• Phone (type: string?) — phone
• Email (type: string?) — email
• CreatedAt (type: DateTime?) — snapshot creation timestamp

Notes

• All operations are tenant-aware
• All state-changing operations are audited
• pageSize=0 returns only totalCount with an empty items array — useful for count-only dashboard queries
• Document lines are always returned ordered by LineNumber, soft-deleted lines are excluded
• Address snapshots are immutable — they do not reflect subsequent changes to the entity's address
• Internal errors are logged but not exposed to clients