iDempiere Carrier Integration: Connecting DHL, FedEx, and UPS for Shipping Automation

Business Case for Carrier Integration

Without ERP ↔ carrier integration, every shipment requires a warehouse operator to open the carrier portal, re-key the AWB details, download the label, paste it on the box, and then re-enter the tracking number back into the ERP. For a 200-shipment-a-day operation, that's 4–6 labor hours and a meaningful error rate.

A proper integration collapses the whole thing into a single click inside iDempiere: ship a package, print the label, book the pickup, and have the tracking number post back to the ERP automatically.

Integration Scope: Rate, Label, Track, Confirm

The standard scope for a full carrier integration has four functions:

1. Rate quote: given weight, dimensions, origin, destination → carrier price
2. Ship / label generation: create the AWB, return the PDF/ZPL label
3. Pickup scheduling: request a pickup window from the carrier
4. Tracking: ingest carrier tracking events and update shipment status in iDempiere

DHL Express API

DHL offers a modern MyDHL API with REST/JSON endpoints for rate shopping, shipment creation, label generation, pickup booking, and tracking. Key endpoints we use:

• POST /rates — get a rate quote with service options
• POST /shipments — create an AWB, returns the base64-encoded label (PDF or ZPL)
• POST /pickups — schedule pickup for the day's manifest
• GET /tracking/{awb} — pull status; or subscribe to tracking webhooks for push updates

Auth is HTTP Basic with your DHL account number + API key. Sandbox and production share the same structure. We cache rate quotes for 15 minutes to keep the UI snappy.

FedEx Ship API

FedEx's REST API (modernized from the legacy SOAP stack) covers rating, shipping, tracking, and pickup. Auth uses OAuth2 client-credentials flow:

• POST /oauth/token — client_id + client_secret → access token (valid 1 hour)
• POST /rate/v1/rates/quotes — rate shopping with all eligible services
• POST /ship/v1/shipments — shipment creation; returns label (PDF, ZPL, or thermal) and tracking number
• POST /pickup/v1/pickups — close-of-day manifest and pickup
• POST /track/v1/trackingnumbers — bulk tracking (up to 30 AWBs per call)

UPS Developer Kit

UPS also offers modern REST endpoints after retiring the SOAP XPCI stack. We use:

• OAuth2 flow for auth
• /api/rating/v1/Rate — rate shopping
• /api/shipments/v1/ship — shipment + label
• /api/track/v1/details/{inquiryNumber} — tracking
• /api/shipments/v1/pickup — pickup scheduling

Multi-Carrier Rate Shopping

For every shippable iDempiere document (M_InOut in draft), we call all three carriers in parallel, get rate quotes, and present a ranked list to the warehouse operator:

• Cheapest — lowest total cost regardless of transit time
• Fastest — shortest committed delivery date
• Cheapest with SLA — lowest cost meeting the customer's required delivery date

Rate quotes are cached for 15 minutes per (origin-destination-weight-service) tuple. One click, and the chosen carrier's label is generated.

Label & AWB Printing from iDempiere

The carrier returns a base64-encoded label (PDF for A4 printers, ZPL for thermal label printers like Zebra ZD420). We attach the label to the iDempiere M_InOut via C_Attachment and the AWB number goes into the shipment's tracking field.

Warehouse clients almost always prefer thermal printers on 4×6" labels. Plan for that hardware in your rollout and test a few hundred labels end-to-end before go-live — thermal printer quirks are real.

Tracking Webhooks & Proof of Delivery

Each carrier supports either webhook push or scheduled pull for tracking updates. We convert carrier status codes to an internal canonical state machine: Picked Up → In Transit → Out for Delivery → Delivered (or Exception). On "Delivered" we capture the POD (name + signature image if available) and attach it to the iDempiere shipment for audit.

Exception Handling & Dangerous Goods

Not every shipment goes through cleanly. Common exceptions:

• Address validation failures — carrier returns "address not serviceable". We auto-retry with a corrected address from our address-validation service before escalating to the operator.
• Weight mismatch — carrier reweighs in transit and posts a surcharge. We ingest weight-correction events and post them as additional landed cost.
• Dangerous goods — lithium batteries, aerosols, etc. require IATA DGR declarations for air shipments. Our DHL/FedEx integration templates include the required fields; ask us for the DGR-ready config.