HTKapp Logo

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).

Quick Actions (Context Menu and Swipes)

  • Context menu (long press):
    • View PDF: Preview of the delivery note.
    • Validate shipment (if in draft): shortcut shown for information; the actual validation is performed from the detail view.
    • 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 (origin_id) 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 (status 0):

  • 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, and POST /shipments/{id}/lines does not exist in Dolibarr's API: shipment lines are created from the originating order. The action has been removed, along with "Reopen (Draft)", whose route does not exist either.

If the shipment is Validated (status 1):

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

If the shipment is Closed (status 2):

  • Create Invoice.
  • Reopen (Draft).
  • Manage Return (Web).

Information

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

Direct links to the associated entities:

  • Customer order of origin (with access to its record, or a "Not synchronized" note if the order is not present locally).
  • Project it is attached to.

Contacts

List of the contacts associated with the shipment, with their role (Delivery, Customer Contact…) and direct access by phone or email.

  • Add a contact: associates a contact of the third party with the shipment (Delivery or Customer Contact role).
  • Unlink a contact: by swiping, removes the contact from the shipment.

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).

Creation from the "+" Button

The "+" button in the top bar of the list opens a blank shipment form:

  • Selection of the recipient third party (customer) (required).
  • Customer reference, dates (delivery, shipping).
  • Logistics information (weight + unit, dimensions + unit, shipping method).
  • Tracking number and URL.
  • Public and private notes, attached project.

Good to know. This blank creation does not add product lines: lines are then added by barcode scanning, or via a creation from an order.

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.

Quick Scan (Draft)

On a draft shipment, the "Scan a product" action opens the barcode scanner: a scan looks up the product, opens a quantity-entry alert, and the line is added to the shipment. If no product matches the barcode, an error message is shown.

Business Behavior and Dolibarr

Life Cycle

  • Draft (0): Initial creation, editable lines (add by scan, delete by swipe), scanning possible.
  • Validated (1): Stock decremented, invoiceable.
  • Closed (2): Marked as delivered. Invoice creation remains possible.
  • At any time from Validated or Closed: a return to Draft is possible.

Rights and Permissions

  • Read: Read permission on the Shipments module required.
  • Create / Modify: The "+" button and the modification actions are conditioned by the Dolibarr expedition.creer permission.
  • 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

← Previous Warehouses Module Next → Customer Invoices Module