Commercial Orders: Sales, Purchases, Customers, and Sellers

The Commercial Orders module is the commercial backbone of Dragon Guard WMS. It manages the four core business entities — customers, sellers, sales order documents, and purchase order documents — and provides the linkage layer that connects outgoing shipments to real commercial transactions. All entities are company-aware: every record is scoped to an active_company_id through ApiControllerBase, preventing cross-tenant data exposure. The MAUI handheld is not involved in this phase; all operations are handled through the Angular web frontend.

Entity Model

The module is built around four entities, each with its own identity key and duplicate-control rules.

Customer

Identified by CompanyId + CustomerNo. Duplicate control is applied on tax ID and external identity.

Seller

Identified by CompanyId + SellerCode. Duplicate control is applied on email and external identity.

Sales Order

Header + lines tracking customer, seller, dates, notes, totals, and Business Central (BC) identifiers.

Purchase Order

Header + lines tracking vendor snapshot, dates, notes, totals, and BC identifiers.

Entity Reference

Customer

Field	Description
`CompanyId`	Tenant company scope
`CustomerNo`	Unique customer code within the company
`Name`	Customer display name
`TaxId`	Tax identification number (duplicate-controlled)
`ExternalIdentity`	Third-party system identifier (duplicate-controlled)
`Address`	Registered address
`Contact`	Primary contact information
`Status`	Active / Inactive

Seller

Field	Description
`CompanyId`	Tenant company scope
`SellerCode`	Unique seller code within the company
`Name`	Seller display name
`Email`	Seller email address (duplicate-controlled)
`ExternalIdentity`	Third-party system identifier (duplicate-controlled)
`Status`	Active / Inactive

Sales Order Header / Line

Field	Description
`CompanyId`	Tenant company scope
`SalesOrderNo`	Auto-generated document number
`CustomerId` / `CustomerName`	Linked customer (snapshot at creation)
`SellerId` / `SellerCode`	Assigned seller (snapshot at creation)
`OrderDate` / `ShipDate`	Key dates
`Notes`	Free-text notes
`Totals`	Line-aggregated document totals
`BcIdentifiers`	Business Central reference fields

Purchase Order Header / Line

Field	Description
`CompanyId`	Tenant company scope
`PurchaseOrderNo`	Auto-generated document number
`VendorNo` / `VendorName`	Vendor snapshot at document creation
`TaxId`	Vendor tax ID at creation time
`Address` / `Contact`	Vendor contact snapshot
`OrderDate` / `ReceiveDate`	Key dates
`Notes`	Free-text notes
`Totals`	Line-aggregated document totals
`BcIdentifiers`	Business Central reference fields

Snapshot Rule

Document creation stores a point-in-time snapshot of master data. When a sales order is created, the customer name, tax ID, address, and contact are copied into the document record. Subsequent changes to the customer master record do not modify existing documents. The same rule applies to vendor data on purchase orders and seller data on sales orders. This ensures that historical documents remain accurate and auditable regardless of future master-data edits.

Vendor Master

Although there is no dedicated Vendor entity exposed in the frontend at this phase, the purchase order stores a full vendor snapshot at creation time using the following fields:

Field	Description
`CompanyId`	Tenant company scope
`VendorNo`	Unique vendor code
`Name`	Vendor name
`TaxId`	Tax identification (snapshot)
`Address`	Registered address (snapshot)
`Contact`	Primary contact (snapshot)
`Status`	Active / Inactive

Frontend Module Structure

All commercial order components live under src/app/sales/. The table below maps each functional area to its frontend location.

Area	Location in `sales/`	Description
Sales order list	`sales-orders/`	Paginated list of all sales orders for the active company
Sales order create / detail	`sales-orders/create` or `sales-orders/:id`	Form for creating and viewing sales order headers and lines
Customer maintenance	`customers/`	Create, list, and edit customers
Seller maintenance	`sellers/`	Create, list, and edit sellers
Purchase order list	`purchase-orders/`	Paginated list of all purchase orders
Purchase order create	`purchase-orders/create`	Form for creating purchase order headers and lines
Shipment create (sales link)	`shipments/create`	Includes the sales-order lookup dialog for linking shipments

The shipment create page (shipments/create) embeds a sales-order lookup dialog that allows an operator to search for and attach an existing sales order to the new shipment. When a sales order is selected, the backend validates that the order belongs to the active company and populates commercial fields from the order snapshot.

Shipment-to-Sales-Order Link

Shipment documents (ShipmentHeaders) support an optional SalesOrderId and SalesOrderNo field.

Without Sales Order
With Sales Order

The shipment is created as a standalone outbound document. Customer name and commercial fields are entered manually. No commercial validation is performed against the sales order layer.

When a salesOrderId is provided:

The backend validates that the sales order belongs to the active company (CompanyId check).
Commercial fields on the shipment (customer name, references) are populated from the sales order snapshot.
Future edits to the sales order master do not affect the shipment’s commercial snapshot.
The link is surfaced in the shipment detail view for traceability.

Duplicate Validation

The backend enforces uniqueness constraints and returns localized error keys when violations occur. The web UI resolves these keys through the Angular i18n layer and displays them in a blocking modal.

Error Key	Entity	Duplicate Field
`validation.salesOrderDuplicate`	Sales Order	Duplicate document reference or BC identifier
`validation.customerDuplicate`	Customer	Tax ID or external identity already registered for the company

Database Migrations

On application startup, Wms.Api calls Database.Migrate() to apply any pending Entity Framework migrations automatically. No manual migration steps are required for new deployments or updates. This ensures the schema is always in sync with the current version of the backend without operator intervention.

API Endpoints

All endpoints are company-aware through ApiControllerBase. The companyId claim is read from the JWT and applied server-side — it does not need to be passed as an explicit query parameter on POST and PUT requests.

Method	Endpoint	Entity	Purpose
`GET`	`/api/customers`	Customer	List all customers for the active company
`POST`	`/api/customers`	Customer	Create a new customer
`PUT`	`/api/customers/{id}`	Customer	Update an existing customer
`GET`	`/api/sellers`	Seller	List all sellers for the active company
`POST`	`/api/sellers`	Seller	Create a new seller
`PUT`	`/api/sellers/{id}`	Seller	Update an existing seller
`GET`	`/api/sales-orders`	Sales Order	List all sales orders for the active company
`POST`	`/api/sales-orders`	Sales Order	Create a new sales order with lines
`PUT`	`/api/sales-orders/{id}`	Sales Order	Update an existing sales order
`GET`	`/api/purchase-orders`	Purchase Order	List all purchase orders for the active company
`POST`	`/api/purchase-orders`	Purchase Order	Create a new purchase order with lines
`PUT`	`/api/purchase-orders/{id}`	Purchase Order	Update an existing purchase order
`GET`	`/api/shipmentheaders`	Shipment	List shipments (see Shipments module)
`POST`	`/api/shipmentheaders`	Shipment	Create shipment, optionally linked to sales order

POST /api/sales-orders
Authorization: Bearer {token}
Content-Type: application/json

{
  "customerId": 12,
  "sellerId": 3,
  "orderDate": "2025-06-01",
  "shipDate": "2025-06-10",
  "notes": "Urgent delivery",
  "lines": [
    { "itemId": 88, "quantity": 100, "unitPrice": 15.00 }
  ]
}

POST /api/customers
Authorization: Bearer {token}
Content-Type: application/json

{
  "customerNo": "C-00042",
  "name": "Retail Partner S.A.",
  "taxId": "RUC-0001234567",
  "address": "Av. Principal 123, Ciudad",
  "contact": "[email protected]",
  "status": "Active"
}

Getting Started

Architecture

Core Modules

Admin & Operations

RFID & Supreme Admin

Developer Guide

Commercial Orders: Sales, Purchases, Customers, and Sellers

Entity Model

Customer

Seller

Sales Order

Purchase Order

Entity Reference

Customer

Seller

Sales Order Header / Line

Purchase Order Header / Line

Snapshot Rule

Vendor Master

Frontend Module Structure

Shipment-to-Sales-Order Link

Duplicate Validation

Database Migrations

API Endpoints

Build docs developers (and LLMs) love

Getting Started

Architecture

Core Modules

Admin & Operations

RFID & Supreme Admin

Developer Guide

Documentation Index

​Entity Model

Customer

Seller

Sales Order

Purchase Order

​Entity Reference

​Customer

​Seller

​Sales Order Header / Line

​Purchase Order Header / Line

​Snapshot Rule

​Vendor Master

​Frontend Module Structure

​Shipment-to-Sales-Order Link

​Duplicate Validation

​Database Migrations

​API Endpoints

Build docs developers (and LLMs) love

Entity Model

Entity Reference

Customer

Seller

Sales Order Header / Line

Purchase Order Header / Line

Snapshot Rule

Vendor Master

Frontend Module Structure

Shipment-to-Sales-Order Link

Duplicate Validation

Database Migrations

API Endpoints