Preparation & delivery

This area covers what happens between the back-office confirmation of an order and its delivery (cahier §3, §4.4, §11, §14.2, reference screen 5): preparation, shipping, proof of delivery, the carriers HOCO works with, and the delivery fee charged at checkout. It is run by the Responsable livraison in the back-office (BO); resellers follow it in their apps (RA, RW) through the order tracker. The server's fulfillment module owns Delivery and Carrier; the order moves through admin.orders.transition and admin.deliveries.* (API › Orders & delivery); statuses on Lifecycles › Delivery.

ID	Requirement	Release	Priority	Source	Apps
DLV-01	Preparation workflow (picking list) up to 'ready'	V1	MUST	§3, §4.4	API · BO
DLV-02	Shipping: carrier assignment (own fleet or company), tracking number	V1	MUST	§4.4	API · BO
DLV-03	Delivery confirmation with proof (photo, recipient name)	V1	MUST	§3, §4.4	API · BO
DLV-04	Carrier list management (API-capable vs manual)	V1	SHOULD	§11	API · BO
DLV-05	Carrier API integration (shipment creation, tracking webhooks)	V2	SHOULD	§11, §14.2	API
DLV-06	Delivery-fee policy (free threshold, per wilaya)	V1	SHOULD	Reference screen 5	API · BO

Settings used in this areaCopy Anchor Link

RequirementsCopy Anchor Link

DLV-01 — Preparation workflow up to readyCopy Anchor Link

Statement — The system shall manage the preparation of every confirmed order — delivery board, picking list, picking and packing — until it is ready to leave.

Rules

1. Confirmation (ORD-14) creates a Delivery in TO_PREPARE with a proposed mode from the address. The delivery board (BO-42, admin.deliveries.list, delivery.view) shows one column per status — À préparer, En préparation, Prête, Expédiée, Livrée, Échec de livraison — or the same records as a list, with filters by wilaya, mode, carrier and date, and late orders highlighted.
2. « Commencer la préparation » moves the order VALIDATED → PREPARING (admin.orders.transition, orders.update or delivery.update); the user becomes the picker.
3. The picking list (admin.deliveries.pickingList, JSON or A4 PDF) shows the order number with its barcode, the reseller, the address and landmark, the notes, the warehouse and per line brand, product, variant, SKU, barcode and quantity — sorted by brand then SKU, no prices.
4. A picking shortage is handled before packing by a controlled modification that decreases or removes the line, with a reason the reseller sees (ORD-05); quantities can never be increased while PREPARING.
5. « Prête » moves PREPARING → READY with the number of parcels (≥ 1, 400 VALIDATION_FAILED otherwise); the delivery note BL-YYYY-NNNNNN is allocated and its PDF generated (ORD-12).
6. The Delivery mirrors the order in the same transaction; each move is journaled and pushed live to the reseller (ORD-15).

Acceptance criteria

• Confirming an order adds a card under À préparer on BO-42 without reload.
• The picking list PDF of CMD-2026-000158 lists its lines by brand with SKU, barcode and quantity and no price.
• Marking an order Prête without parcels returns 400 VALIDATION_FAILED; with 2 parcels it allocates BL-2026-000123 and the delivery note can be downloaded.
• A delivery manager without orders.update can move orders through preparation (holds delivery.update) but cannot cancel them.

Data — Delivery, Order, OrderStatusChange, OrderChange, File (picking list, delivery note), NumberSequence.

Interfaces

• Screens: BO-42 Delivery board
• API: admin.orders.transition POST /admin/orders/{orderId}/transitions · admin.deliveries.list GET /admin/deliveries · admin.deliveries.pickingList GET /admin/deliveries/{deliveryId}/picking-list

DLV-02 — Shipping with carrier or own fleet and tracking numberCopy Anchor Link

Statement — The system shall record how each order is delivered — HOCO's own drivers, a delivery company or pickup at the depot — with the carrier, tracking number or driver, and mark it shipped.

Rules

1. Delivery data (admin.deliveries.update, delivery.update): mode (DeliveryMode: OWN_FLEET, CARRIER, PICKUP, changeable until shipping), carrier, tracking number (3–60 characters), driver name and phone (E.164), planned date, parcels, note.
2. Shipping guard (READY → SHIPPED): OWN_FLEET needs a driver name and phone; CARRIER needs an active carrier covering the delivery wilaya and a tracking number when the carrier requires one (422 DELIVERY_INFO_REQUIRED with details.missing; 422 CARRIER_INACTIVE); a PICKUP order does not ship — it goes from READY to DELIVERED at handover (DLV-03).
3. Shipping deducts stock (SHIPMENT movements) and issues the invoice with the defaults (STK-03, FIN-01); the tracking link is built from the carrier's template (https://…/{tracking}).
4. Failed attempt: on a shipped order, attempt (reason required, next attempt date) sets the delivery FAILED while the order stays SHIPPED; reattempt puts it back to SHIPPED; after the last failure the goods come back with SHIPPED → RETURNED (refused at the door), which creates a return in transit whose reception re-enters the stock automatically (ORD-13).
5. A delivered, returned or cancelled delivery cannot be edited (409 DELIVERY_NOT_EDITABLE).
6. Notifications to the reseller: shipped (with carrier and tracking link), failed attempt (« Livraison non aboutie — nouvelle tentative le … »), returned — push, inbox and live.

Acceptance criteria

• Shipping a CARRIER order without tracking number for a carrier that requires one returns 422 DELIVERY_INFO_REQUIRED with missing: ["trackingNumber"].
• Shipping with carrier Yalidine and tracking YAL-58219004 moves the order to SHIPPED, posts the stock deduction, issues the invoice and sends the reseller a push with the tracking link.
• A failed attempt keeps the order SHIPPED, shows Échec de livraison on BO-42 and notifies the reseller with the next attempt date.
• Editing a delivered delivery returns 409 DELIVERY_NOT_EDITABLE.

Data — Delivery, Carrier, Order, StockMovement, Invoice.

Interfaces

• Screens: BO-42 Delivery board
• API: admin.deliveries.list GET /admin/deliveries · admin.deliveries.update PATCH /admin/deliveries/{deliveryId}

DLV-03 — Proof of deliveryCopy Anchor Link

Statement — The system shall record a proof of delivery — recipient name, time and a photo or signature — before marking an order delivered, and record the cash collected on cash-on-delivery orders.

Rules

1. admin.deliveries.proof (delivery.update): recipient name (2–120), delivery time (after shipping, at most 5 minutes in the future), a DELIVERY_PROOF photo or signature (required while delivery.proofPhotoRequired is true — 422 DELIVERY_PROOF_REQUIRED), optional note.
2. Allowed on a SHIPPED order, or READY with mode PICKUP (handover at the depot); otherwise 409 ORDER_TRANSITION_NOT_ALLOWED. The order and delivery become DELIVERED; a move to DELIVERED through the generic transition is refused (422 DELIVERY_PROOF_REQUIRED).
3. Cash collected on a CASH_ON_DELIVERY order creates a Payment (PAY-…, status PENDING_VERIFICATION) linked to the order and its invoice; finance confirms it (FIN-03) — delivery staff never confirm money.
4. Delivery starts the return and after-sales windows, makes the reseller ACTIVE after a first order (CRM-04) and notifies the reseller (« Commande livrée »).
5. In V1 proofs are entered in the back-office from what the driver or carrier reports; a driver app is not in scope. Proof photos are private files served by signed URLs.

Acceptance criteria

• Recording the proof of a shipped order with recipient Hichem Bouzid and a photo marks it DELIVERED; RA-22 shows Livrée live.
• Without photo while the setting is on, the API returns 422 DELIVERY_PROOF_REQUIRED.
• Recording 10 234,00 DA collected creates PAY-2026-000081 PENDING_VERIFICATION visible to finance in BO-45.
• A proof on a VALIDATED order returns 409 ORDER_TRANSITION_NOT_ALLOWED.

Data — Delivery (proof), File (DELIVERY_PROOF), Order, Payment.

Interfaces

• Screens: BO-42 Delivery board
• API: admin.deliveries.proof POST /admin/deliveries/{deliveryId}/proof

DLV-04 — Carrier list managementCopy Anchor Link

Statement — The system should let the back-office maintain the list of carriers — HOCO's own fleet and delivery companies — with their coverage, tracking link template and whether they offer an API.

Rules

1. A Carrier has a unique name (2–80, 409 DUPLICATE_VALUE), a mode (OWN_FLEET, CARRIER), a phone, a tracking URL template containing {tracking} (https only), whether a tracking number is required, the wilayas covered (empty = all), an API-capable flag (informative in V1, used by V2 integration) and an active flag.
2. Managed in BO-43 (admin.carriers.crud): read with delivery.view (so the board can offer the picker), write with delivery.administer.
3. A carrier used by deliveries is deactivated, never deleted; an inactive or non-covering carrier cannot be chosen for a delivery (422 CARRIER_INACTIVE).

Acceptance criteria

• Creating a carrier with a template lacking {tracking} returns 400 VALIDATION_FAILED.
• A carrier covering wilayas 31, 46 and 29 is not offered for a delivery to wilaya 16.
• Deactivating Yalidine removes it from the picker and keeps it on past deliveries.

Data — Carrier, Delivery.

Interfaces

• Screens: BO-43 Carriers
• API: admin.carriers.crud GET · POST · PATCH /admin/carriers[/{carrierId}]

Notes / open points — Which carriers HOCO uses is D-08.

DLV-05 — Carrier API integrationCopy Anchor Link

Statement — The system should, in V2, create shipments and follow their tracking through the API of the carriers that offer one.

Rules

1. For an API-capable carrier, shipping creates the shipment through its API (parcels, address, cash to collect) and stores the carrier's tracking number and label PDF.
2. The carrier's tracking webhooks (signature verified, processed idempotently) update the delivery: in transit, delivered (with the carrier's proof), failed attempt, returned to sender — mapped to the same transitions as manual entry.
3. When the API is down, the delivery falls back to manual entry without blocking the order.

Acceptance criteria

• A shipment created for an API-capable carrier stores the carrier's tracking number; its delivered webhook marks the order DELIVERED.
• The same webhook received twice changes nothing the second time.

Data — Carrier, Delivery, integration logs.

Interfaces

• Screens: none dedicated
• API: no dedicated operation

Notes / open points — V2 (SRV-34), depends on D-08.

DLV-06 — Delivery-fee policyCopy Anchor Link

Statement — The system should compute the delivery fee of an order from a configurable policy — free, or per wilaya with a free-delivery threshold — and show it before checkout.

Rules

1. delivery.feePolicy = FREE (default): every order that reaches the minimum amount is delivered free; the cart shows « Frais de livraison : Offerts » (reference screen 5).
2. WILAYA_TABLE: the fee is the amount HT of delivery.feeByWilaya for the delivery address's wilaya (or the table's default); it is waived when the merchandise total TTC after promotions reaches delivery.freeThresholdTtc, or when a FREE_DELIVERY promotion applies (PRM-01); PICKUP is always free.
3. The fee is HT with VAT at 19 % added to the totals (PRC-04); the cart computes it for the default address, cart.checkoutOptions for each address, and checkout freezes it on the order — a later policy change never alters an order.
4. A changed fee between display and checkout makes the checkout answer 409 CART_CHANGED (PRC-05).
5. The policy and table are business settings (ADM-03), changed by settings.administer and journaled.

Acceptance criteria

• With the default policy, a cart above the minimum shows Offerts and deliveryFee: 0.
• With WILAYA_TABLE, a fee of 50 000 HT for wilaya 31 and a threshold of 5 000 000 TTC: a cart of 4 200 000 TTC delivered in Oran gets 50 000 HT (59 500 TTC) of fee; a cart of 5 100 000 TTC gets 0.
• A FREE_DELIVERY promotion targeted at the reseller sets the fee to 0 whatever the table.

Data — Setting, Order (frozen fee), Cart, Promotion.

Interfaces

• Screens: RA-18 Checkout
• API: cart.checkoutOptions GET /cart/checkout-options

Notes / open points — Free delivery or a fee table is D-20 (default: free).

Error codesCopy Anchor Link