Aramex

What this guide covers

Booking an Aramex courier from inside mywork — submitting a waybill, scheduling a collection, tracking the shipment, and printing the label. Aramex is embedded in Sales Shipments and External Service Shipments rather than being its own page; this article is the integration reference.

For the parent shipment workflows see Sales Shipments and External Service Shipments.

Where to find it

There is no top-level Aramex page. The integration appears as a Request Courier button (and the related Track / Download Waybill actions) inside:

• Sales Shipments → row → Request Courier
• External Service Shipments → row → Request Courier

Who can do what

• Warehouse staff with access to the parent shipment view can request couriers, track, and download labels. There is no separate Aramex permission.
• Site admin (ADMIN) bypasses everything.
• Aramex account credentials are hardcoded in the integration (AramexShipmentView.init()) — the same account number books every shipment.

Booking a waybill

1. From a shipment row, click Request Courier. The dialog opens.
2. Sender details are pre-filled from Solar MD's hardcoded address. Your login name auto-fills as the sender contact person; override if someone else is doing the dispatch.
3. Receiver details pre-fill from the customer record (Sales Shipment) or ROS delivery address (External Service Shipment). Verify and edit if needed — typos here mean the package goes to the wrong place, not back to the system.
4. Set the service type:
   • PEX — Road Express (default; recommended for most domestic).
   • SMP — Same-day in-metro (premium).
   • EMD — Economy.
   • ONP — Overnight Priority.
   • PEC — Economy Courier.
   • PPX / PDX — international.
5. Add parcels. For each parcel, all three of height, length, width are required and must be > 0 (in cm). Aramex rejects the waybill if any dimension is missing.
6. Pickup date — when the courier should collect from the warehouse.
7. Insurance is off by default (requireInsurance = false); ticking it adds the insuranceValue to the waybill.
8. Payment type defaults to P (account holder); 3 is third-party (rarely used here).
9. Document flag (isDocument) — tick if you're shipping documents only; affects Aramex pricing/handling.
10. Click Submit. Aramex returns a status_code (0 = success) plus a waybill number (format LAR…). The collection request fires automatically right after with the same details, returning a collection reference (format D…).

Both references store pipe-delimited (<LAR-number> | <D-number>) in the shipment's customerRef and trackingNumber fields. Don't edit those fields manually — the parsing relies on the format.

Booking a collection for an existing waybill

Sometimes a waybill is created outside the system (paper booking, supplier-arranged) and you only need the collection scheduled:

1. Open the shipment, click Request Courier.
2. In the dialog, switch to Book Collection (Existing Waybill) mode.
3. Type the existing LAR… waybill number.
4. Submit. Aramex returns the collection reference; the system stores it on the shipment.

Tracking and label download

• Track Waybill — extracts the LAR… number from the tracking field and calls Aramex's tracking API. Shows the live status (booked / collected / in transit / delivered) and the latest scan log.
• Track Collection — extracts the D… reference and calls the collection-tracking API. Shows the pickup status (scheduled / collected / failed).
• Download Waybill — constructs the Aramex PDF URL (https://nservice.aramex.co.za/Home/GeneratePDFTemplateOne/?waybill_number=LAR…) and streams the PDF for printing on the configured label printer.

The PDF is hosted on Aramex; the URL works for anyone who knows the waybill number — treat the waybill number as sensitive when sharing it.

Common errors and fixes

• "Cannot submit shipment: Dimensions of a parcel is not complete" — height, length, or width is missing or zero on at least one parcel. Fill all three for every parcel.
• status_description text from Aramex (variable, surfaced verbatim) — most common:
  • Invalid postal code — verify the receiver address; postal-code mismatch with city is rejected.
  • Account suspended — Aramex has put the account on hold (typically billing); contact the buyer.
  • Phone number format — the receiver phone field doesn't match Aramex's expected format. Strip spaces / dashes / country codes and try again.
  • Service unavailable for destination — the chosen service type doesn't cover the receiver's area. Switch to a fall-back like PEX.
• "Failed to book collection: [status_description]" — shown as a yellow warning. The waybill itself created OK; only the collection failed. Schedule pickup manually or retry.
• "Failed to create waybill: [status_description]" — shown as a red error. The waybill did not create; nothing is booked. Fix the offending field and resubmit.
• Network / timeout error during PDF download — the Aramex PDF endpoint is occasionally slow. Wait a moment and click Download again.

Tips and gotchas

• Hardcoded credentials — every booking uses the same Aramex account (251656). If credentials need rotating, the change is in AramexShipmentView.init() and requires a redeploy. There is no UI for it.
• Country code is hardcoded ZA — international shipments technically work but Aramex assumes a domestic address mapping. Cross-border shipments need extra setup.
• Default service is PEX — change deliberately for premium / international.
• Parcels are not auto-detected from Sales Order items. You enter parcel count + dimensions yourself. There's no "calculate from line items" shortcut.
• Insurance is off by default. Tick deliberately for high-value shipments; the insurance value field is otherwise ignored.
• Tracking format is composite. "LAR1234567 | D9876543" — pipe-separated. The Track buttons parse this automatically; don't reformat it.
• Treat the waybill number as sensitive. The PDF endpoint requires no auth — anyone with the number can download the label and pretend to be the dispatcher.