Shipments Module

The HtkDoli Shipments module lets you view, create and track the shipments linked to your customer orders. It follows the complete Dolibarr shipment life cycle (Draft → Validated → Closed/Delivered) and includes barcode scanning and invoice generation actions.

⚠️ Good to know — creating a shipment from an order. Creating a shipment from a customer order is done by selecting the source warehouse and the quantities to ship per line. Shipping requires stockable products that have stock in the chosen warehouse (Dolibarr constraint); a line without a stockable product cannot be shipped.

Interface and Features (List)

The main view displays the list of all your shipments, with a floating header that hides on scroll.

Viewing and Searching

Search bar: Search by shipment reference, customer name or tracking number.
Sorting:
- Date (Newest → Oldest, Oldest → Newest)
- Reference (A→Z, Z→A)
Filters by status (with an item count):
- All
- Draft
- Validated
- Closed
Grouping: When no search is active, the list is grouped by month (date sort) or by the first letter of the reference (reference sort), with an index bubble shown while scrolling.
Refresh: Button in the header with a status indicator (grey = needs refreshing, blue = in progress, green = success, red = error). Keyboard shortcut ⌘R.

Information Displayed (Shipment Cards)

Each row represents a shipment with:

Its reference (e.g. SH2404-0001).
The recipient customer name.
The expected delivery date if set, otherwise the creation date.
The status as a colored dot (Draft, Validated, Closed).

Context menu (long press):
- View PDF: Preview of the delivery note.
- Validate shipment (if in draft): validates the shipment from the list, as from the record (queued then sent to Dolibarr).
- Edit.
- Delete.
Swipe left (trailing edge): Delete (immediate deletion, without its own confirmation alert).
Swipe right (leading edge): Edit.

Pagination

Loading in batches of 50 shipments with a "Load more" button.
Pull-to-refresh to resynchronize.

No "+" button on the list

A shipment is created from a customer order's detail view ("Create a shipment"), never from the list: Dolibarr requires the originating order at creation, and a "free" shipment is rejected by the server.

Detail View (Viewing a Shipment)

Tapping a shipment in the list takes you to its full record.

Header (Hero Section)

Shipment reference.
Linked customer name.
Status badge (Draft / Validated / Closed).

Workflow Actions (depending on status)

If the shipment is a Draft:

Validate shipment: Moves to Validated status, triggers the stock decrement on the Dolibarr side.

⚠️ No more "Scan a product". Scanning led to adding a line, which Dolibarr's API does not allow: shipment lines are created from the originating order. The action has been removed, along with "Reopen (Draft)", which the API does not allow either. A line of a draft is deleted with a long press on the line.

If the shipment is Validated:

Create Invoice: Generates a draft customer invoice from the shipment.
Mark Delivered / Close: Moves to Closed status.
Manage Return (Web): Opens the return management in the browser (Dolibarr feature not available through the API).

If the shipment is Closed:

Create Invoice.
Manage Return (Web).

Information

Customer Reference (if set)
Creation Date
Shipping Date
Delivery Date (or "Not set")

Contacts

The card says it itself: a shipment's contacts can neither be viewed nor edited from the app, as Dolibarr's API does not offer them. Use the Dolibarr web interface.

Logistics

If set:

Weight (with its unit)
Dimensions (width × height × depth)

Carrier Tracking

Package tracking number.
"Track package" link that opens the carrier's tracking URL in the browser (if set).

Content

List of the shipped products with their label, reference, optional description and the shipped quantity. On a draft shipment, a line can be deleted by swiping. A "No line or detail not synchronized." note is shown if the record has not yet been detailed by the server.

Documents

Viewing, downloading, PDF preview.
Adding documents once the shipment is synchronized on the server side.

Notes

Public note.
Private note (internal use).

Floating Header Actions

View PDF (if the shipment is synchronized).
Edit (if you have the create/modify permission).
Delete (with confirmation).

Creation and Editing

Creation from a Customer Order

From a customer order record (the "Create a shipment" action), the creation screen lets you:

View the order of origin and its customer.
Choose the source warehouse.
Set the quantities to ship per order line. The app automatically computes the remaining to deliver (ordered quantity minus already shipped quantities) and proposes it by default.
Confirm to create the shipment as a draft (synchronized in the background).

Editing

The edit form offers the same fields (customer reference, dates, logistics, shipping method, tracking, notes, project). The change is applied optimistically locally and then synchronized.

Business Behavior and Dolibarr

Life Cycle

Draft: Initial creation from the order; a line is deleted with a long press.
Validated: Stock decremented, invoiceable.
Closed: Marked as delivered. Invoice creation remains possible.
Returning to Draft is done from the Dolibarr web interface.

Rights and Permissions

Read: Read permission on the Shipments module required.
Create / Modify: The "+" button and the modification actions are conditioned by the Shipments module create/edit right.
Some advanced operations (return management) are not exposed by the Dolibarr API and open in the browser.

Synchronization

List paginated by 50. The customer name and any missing lines are completed in the background during synchronization.
A shipment's detail is fetched when the record is opened.
Actions (validation, closing, reopening, invoice creation, shipment creation/modification) are queued and then synchronized.
Associated documents are loaded in the background.

Screenshots

1 screenshot — click to enlarge