CargoWise Integration
Push extracted document data directly to your CargoWise One instance
Overview
The CargoWise integration connects StarShipper directly to your CargoWise One instance via the eAdaptor API. Shipment data is mapped to CargoWise Universal XML and pushed to create or update the record on your side, with the source documents attached as eDocs. You choose the target module per connection: Forwarding for shipments and consols, or Liner & Agency for bills of lading. They are different CargoWise products, so a shipping agency and a freight forwarder do not send to the same place.
Automatic Push
Data sent to CargoWise as soon as documents are approved
Universal XML
Standard CargoWise XML format with intelligent field mapping
Encrypted Credentials
All passwords encrypted at rest with AES-256
Prerequisites
What you need before setting up the integration
What you need depends on which eAdaptor your CargoWise instance exposes. WiseTech is retiring the SOAP eAdaptor in favour of eAdaptor Next, and a WiseCloud-hosted instance accepts eAdaptor Next only. Your CargoWise administrator will know which you run.
eAdaptor Next endpoint (WiseCloud and current instances)
Your base URL from Registry > EDI Messaging > eAdaptor > Inbound, with the endpoint path on the end:
https://[enterprise][server]services.wisegrid.net/eAdaptorNextOAuth credentials and a certificate
Set up an EDI Client for StarShipper under Maintain > EDI Messaging > EDI Client Details, then give us the client ID, tenant ID, token URL and scope from your eAdaptor Next Postman collection. We generate the key pair and hand you the certificate to register. WiseCloud requires this method; self-hosted instances may use a username and password instead.
eAdaptor WSDL URL (legacy SOAP instances)
Note the endpoint filename is spelled “eAdapter” even though the product is eAdaptor. With a username and password from your eAdaptor Inbound Authentications:
https://[instance].ediportal.cargowise.com/eAdapterStreamedService.wsdlCompany code and eDoc types
Your 9-character organization code (About > Company details) identifies the recipient. Your instance’s 3-character eDoc type codes decide how attached documents are labelled on the eDocs tab; without them we fall back to our own defaults.
Setup Guide
Connect CargoWise in a few steps
Go to Integrations
Navigate to Integrations > Connections in the sidebar and click "Add Connection".
Select CargoWise
Choose "CargoWise" as the integration type. Enter a descriptive name like "CargoWise Production" or "CW Staging".
Enter Your Credentials
Fill in the WSDL URL, username, password, and optionally the Client ID and Org Code. Passwords are encrypted before storage.
Test the Connection
Click "Test Connection" to verify your credentials work. This sends a ping to CargoWise and confirms the eAdaptor is reachable.
Enable and Configure Routes
Save the connection, then set up routing rules to specify which inboxes and document types should be sent to CargoWise (see below).
Routing Rules
Control which shipments get sent to CargoWise
A CargoWise connection dispatches the whole shipment as one Universal XML message, so its route always covers the organisation and there is no per-document-type selector. Webhooks are the only destination that offers one. How each destination is scoped →
What a route can filter on is the shipment itself:
| Filter | Options | Description |
|---|---|---|
| Mode | Sea, air, road | Only shipments on the selected transport modes are sent |
| Shipment status | One or more shipment statuses | Holds a shipment back until it reaches a status you nominate |
| Requires containers | On or off | Skips a shipment with no containers on it yet |
Tip: Start with one mode and a status filter to verify everything works end to end, then widen the route.
XML Format & Field Mapping
How document data maps to CargoWise Universal XML
StarShipper generates CargoWise Universal XML (2011/11 v1.1) from your extracted document data. The mapper intelligently handles field name variations and normalizes values to CargoWise standards.
Automatic Field Mapping
| Document Field | CargoWise Field | Auto-Normalization |
|---|---|---|
| House B/L, HBL Number | WayBillNumber | Capped at the schema length |
| Master B/L, MBL Number | DataTarget Key (forwarding consol) | Universal has no master bill element |
| Your job number | OwnerRef | Capped at the schema length |
| Booking Number | BookingConfirmationReference | Capped at the schema length |
| Port of Loading, POL | PortOfLoading | UN/LOCODE (e.g., CNSHA) |
| Port of Discharge, POD | PortOfDischarge | UN/LOCODE (e.g., AUBNE) |
| Container Numbers | ContainerNumber | ISO 6346 validated |
| Transport Mode | TransportMode | SEA, AIR, ROA, RAI |
| Container Mode | ContainerMode | FCL, LCL, BBK, AIR |
Smart normalization: Port names like "Sydney" are automatically converted to UN/LOCODE format (AUSYD). Country names like "Australia" become ISO codes (AU). Container numbers are validated against ISO 6346 including check digit verification.
eDoc type codes: CargoWise files each attached document under a 3-character type code, and every instance configures its own list. StarShipper ships proposed defaults (OBL, HBL, CIV, PKL and so on) so attachments work before anyone asks, and your real codes can be set per connection without a deploy. Send us your eDoc type list when you set up the connection and the mapping is done once.
DataTarget types
A message carries a DataTarget Type that tells CargoWise which entity it is about. On the Forwarding module a house-level job goes as ForwardingShipment keyed on the house bill, and a master-level one as ForwardingConsol keyed on the master bill. On Liner & Agency it goes as BillOfLading. That type, and the key beside it, are what let CargoWise match an existing record instead of creating a duplicate.
On the Bill of Lading module the key is CargoWise's own job number, which nothing in CargoWise ever tells us. We leave the key out and let CargoWise match on references, which its mapping guide documents as the fallback. Sending a carrier bill number in its place would risk overwriting an unrelated bill.
Troubleshooting
Common issues and how to resolve them
Connection Test Failed
Cause: Invalid WSDL URL or incorrect credentials.
Solution: Verify the WSDL URL is correct and the username/password are for eAdaptor inbound access (not the CargoWise login). Ask your CW admin to confirm the credentials in the user registry.
Document Not Appearing in CargoWise
Cause: Routing rules may not match the document, or the connection may be disabled.
Solution: Check that the connection is enabled, the inbox is included in routing rules, and the document type and status match the configured filters. Review the activity log at Integrations > Activity for delivery status.
Missing Fields in CargoWise
Cause: The document may not have all fields extracted, or field names may not match expected patterns.
Solution: Check the extracted data on the document review page. If fields are missing, try re-extracting the document. The field mapper supports many common name variations automatically.
Delivery Failed: Timeout
Cause: The CargoWise eAdaptor service may be temporarily unavailable.
Solution: Check that the CargoWise eAdaptor is running and accessible. You can resend the document from the document review page once the service is back up.
Activity Log
Each CargoWise dispatch attempt is logged in the integration activity feed. Go to Integrations > Activity to see delivery history, response status, and error details for troubleshooting.