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

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/{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

Behavior:

• Updates all provided fields
• 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
• 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

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

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