Shipmondo Connector – Setup and Field Mapping

Prev Next

Overview

The Shipmondo Shipping Connector sends finished waybills from Business Central to Shipmondo as shipments, and writes the Shipmondo shipment ID and tracking number back to the waybill. Labels are printed by Shipmondo on the printer linked to the packing station.

The connector has two parts:

  • Business Central app (Shipmondo Shipping Connector, version 28.4) on top of Shipping Manager and Abakion Manager Foundation. It holds the setup and triggers the send.
  • Power Automate solution (SMShipmondo 1.0.0.15) with two flows: one for Shipmondo Production and one for the Shipmondo Sandbox. The flow reads the waybill through the Shipping Manager API, builds the Shipmondo request and calls the Shipmondo REST API v3.

The same flow also serves Get Freight Quote, which returns price options from Shipmondo for a planned shipment.

Prerequisites

  • Shipping Manager installed and set up (number series, sender information, shipping agents and services).
  • A Shipmondo account with an API user (API user and API key).
  • A Microsoft Entra ID app registration with access to the Business Central API (Client ID and Client Secret), set up by your partner or IT department. See How to get BC Client ID and BC Client Secret for Connector.
  • A Power Automate environment where the SMShipmondo solution can be imported.

Setup

Setup takes ten steps: activate the app, connect Power Automate, create the connector, then map shipping agents and packing stations.

  1. Activate the app. Run the assisted setup Abakion Shipmondo Connector, enter your email address and choose Activate Trial. This starts the 30-day trial for both the Shipmondo connector and Shipping Manager.
  2. Enable the connector. Open Shipping Manager Setup and turn on Shipmondo under Connectors. Waybills are not sent while this is off.
  3. Get Shipmondo API credentials. In the Shipmondo portal, create an API user. You get an API user and an API key. These are entered as Shipmondo Client-ID and Shipmondo Client Secret. See How to get Shipmondo Client ID and Client Secret.
  4. Get Business Central API credentials. Your partner or IT department creates an Entra ID app registration with access to the Business Central API. You need its Client ID and Client Secret. See How to get BC Client ID and BC Client Secret for Connector.
  5. Import the Power Automate solution. Import SMShipmondo and turn on the flow that matches your environment (Production or Sandbox). Copy the URL of the flow's HTTP trigger. See How to Get the Power Automate Link for Send Waybill.
  6. Create the connector. Open Connectors, create a new connector and fill in the Connector Card:
Field What to enter
ID / Description Your own code and name, for example SHIPMONDO
Type Shipmondo Connector. Manager Type is set to Shipping Manager automatically.
Email for Errormessages Can be filled in, but the current Shipmondo flow does not send error emails. Errors are logged in the Integration Error Log.
BC Client Id / BC Client Secret The Entra ID app credentials from step 4
Shipmondo Environment Production for live shipments, Sandbox for testing
Shipmondo Client-ID / Shipmondo Client Secret The Shipmondo API user and API key from step 3
SyncWaybill (Functionality) On. Waybills are only sent automatically when this is on.
Send Waybill (Power Automate URLs) The HTTP trigger URL from step 5
  1. Map shipping agents. On the Connector Card, choose Map Shipping Agents. Add one line per shipping agent and service. See How To Map Shipping Agent and Shipping Services.
Field What to enter
Shipping Agent Code / Service Code The Business Central shipping agent and service
External Shipping Agent ID The Shipmondo product code for the carrier product
External Shipping Agent Service Code The Shipmondo service codes, comma-separated (may be blank)
Own Agreement On if you use your own carrier agreement in Shipmondo, off to use Shipmondo's agreement. If you upgrade from an earlier version, see Update 28.4.
  1. Set up packing stations. On each Packing Station, fill in Hostname, Printer and Label Format exactly as they appear for the printer in the Shipmondo portal. Labels are then printed on that printer. See How to integrate with the Shipmondo Print Client.
  2. Optional: freight quotes. On the Connector Card, turn on Enable Freight Quote and select the Freight Quote Item No. used for the freight line. See Freight quotes.
  3. Test. Use Test BC Connection and Test Connector Endpoint on the Connector Card. Then send a waybill with the Sandbox environment and the Sandbox flow.

Validation before sending. A waybill is rejected if Shipmondo is not enabled in Shipping Manager Setup, or if any of the four credential fields or Shipmondo Environment is blank.

Environment and flow must match. The flow decides which Shipmondo environment is called: the Production flow calls Production and the Sandbox flow calls Sandbox. Make sure Send Waybill points to the flow that matches Shipmondo Environment.

How a waybill is sent

A waybill is sent to Shipmondo automatically when its status changes to Packing Finished and its connector is a Shipmondo connector with SyncWaybill on.

  1. The waybill gets Integration Status = Ready to Send, and Business Central calls the Send Waybill flow URL.
  2. The flow answers at once (accepted) and continues in the background.
  3. The flow reads the waybill, its waybill lines (packages) and its customs lines through the Shipping Manager API.
  4. If the waybill has a packing station, the flow reads its Hostname, Printer and Label Format.
  5. The flow creates the shipment in Shipmondo (POST /api/public/v3/shipments) and Shipmondo prints the label.
  6. The flow writes the Shipmondo shipment ID and package number back to the waybill.
  7. The waybill status changes to Shipping Agent Ordered and Integration Status to Successfully Sent.
  8. The full Shipmondo response is saved in the Integration Activity Log.

If a step fails, Integration Status is set to Error and the details are saved in the Integration Error Log:

Step that failed Error text in Business Central
Reading the waybill from Business Central Error when fetching Waybill from BC
Creating the shipment in Shipmondo Send Shipment to Shipmondo failed (with Shipmondo's response)
Writing the tracking number back Shipment sent to Shipmondo but update Waybill in BC failed
Setting the status to sent Shipment sent to Shipmondo but update Waybill status in BC failed

Field mapping

The tables show which Business Central field fills each field in the Shipmondo shipment request. Fields not listed are not sent.

Data sent from Business Central to the flow

When a waybill is ready to send, Business Central calls the flow with the following values. The flow then reads the waybill itself through the Shipping Manager API.

Value Business Central source Used by the flow for
BC client ID and secret Connector Card: BC Client Id / BC Client Secret Reading and updating the waybill in Business Central
Tenant, environment and company The Business Central tenant, environment and company the waybill belongs to Calling the right Business Central company
Waybill number Waybill: No. Reading the waybill
Shipmondo client ID and secret Connector Card: Shipmondo Client-ID / Shipmondo Client Secret Authentication against Shipmondo
Own agreement Map Shipping Agents: Own Agreement own_agreement on the shipment
Error message recipients Connector Card: Email for Errormessages Not used by the current flow
Shipmondo API URL Connector Card: Shipmondo Environment Not used: each flow calls its own fixed Shipmondo URL

Shipment

Shipmondo field Business Central source Notes
reference Waybill: No.
product_code Map Shipping Agents: External Shipping Agent ID Looked up by connector, shipping agent and service on the waybill
service_codes Map Shipping Agents: External Shipping Agent Service Code
own_agreement Map Shipping Agents: Own Agreement Off if no mapping line is found
contents Waybill: Type of Goods
pick_up.date Waybill: Pick up date Today's date if blank
service_point.id Waybill: Pickup Point
automatic_select_service_point Fixed: true Shipmondo picks the nearest service point if none is given
test_mode Fixed: false
print Fixed: true

Receiver

Shipmondo field Waybill field
name Name
address1 Address
address2 Address 2
zipcode Post Code
city City
country_code Country/Region Code
telephone and mobile Phone No. (same value in both)
email E-Mail
attention Contact
instruction External Document No.

Sender

Shipmondo field Waybill field
name Sender Name
address1 Sender Address
address2 Sender Address 2
zipcode Sender Post Code
city Sender City
country_code Sender Country/Region Code
telephone and mobile Sender Phone No. (same value in both)
email Sender E-Mail
attention Sender Contact

Parcels

One Shipmondo parcel is sent per waybill line (package), each with quantity 1.

Shipmondo field Waybill line field Conversion
weight Gross Weight Shipmondo uses grams. If the weight unit is KG, the value is multiplied by 1,000; otherwise it is sent as is.
length, width, height Length, Width, Height Shipmondo uses centimetres. If the dimension unit is M, the value is multiplied by 100; otherwise it is sent as is.
packaging Package Type: Description
description Waybill: Type of Goods

Customs

Customs data comes from the waybill's customs lines. Only lines of type Line are sent; header and total lines are skipped.

Shipmondo field Customs line field Conversion
customs.currency_code Currency Code Taken from the customs lines
customs.export_reason Waybill: Reason for Export Sent in lower case; left out if blank
goods.quantity Ship Quantity
goods.country_code Country of Origin
goods.content Tariff Description
goods.commodity_code Tariff No.
goods.unit_value Ship Amount ÷ Ship Quantity Two decimals
goods.unit_weight Ship Net Weight ÷ Ship Quantity In grams (KG × 1,000), rounded; at least 1

Printing

Shipmondo field Packing Station field Notes
print_at.host_name Hostname Sent empty if the waybill has no packing station
print_at.printer_name Printer
print_at.label_format Label Format

Fields not sent to Shipmondo

The following waybill fields are available in Business Central but are not sent by the current flow. Values entered in them do not reach Shipmondo.

Area Fields
Receiver Name 2, County, VAT Registration No., GLN
Sender Sender Name 2, Sender County, Sender VAT Registration No., EORI No.
Bill-to All Bill-to fields
Dates and times Pick up time, Pickup From/To Time, Delivery Date, Delivery From/To Time
Customs and transport Shipment Method Code, Declaration Type, Transport Method
Other Free Text 1–5, Freight Account Code
Waybill lines Net Weight, Volume, Package No.
Customs lines Item No., Description, Ship Gross Weight, Unit of Measure

Freight quotes

Get Freight Quote is available on sales orders, purchase orders and warehouse shipments when Enable Freight Quote is on for the connector. Business Central opens a request window with values from the document, where you can adjust them before sending. The request is sent to the Send Waybill URL, and the flow forwards it to Shipmondo (POST /api/public/v3/quotes/list).

Where the request values come from

Request value Sales order / warehouse shipment Purchase order
Sender The document's location (Company Information if the location has no address) The vendor
Receiver The Ship-to fields on the document The document's location
No. of Packages, Total Gross Weight The document's package and weight totals The document's package and weight totals
Weight unit Default Weight Unit of Measure in Shipping Manager Setup Same

Request sent to Shipmondo

Shipmondo field Freight quote request field Conversion
sender / receiver: address1, address2, zipcode, city, country_code Address, Address 2, Post Code, City, Country/Region Code
parcels.quantity No. of Packages At least 1
parcels.weight Total Gross Weight Converted to grams: sent as is if the weight unit is G, otherwise multiplied by 1,000
parcels.length, width, height Not sent from Business Central Sent as 0

Business Central also sends name, contact, phone, e-mail, net weight, volume, currency, pickup date and the selected shipping agent and service. The current flow does not pass these on, so Shipmondo returns quotes for all available products on the route.

Quote options returned to Business Central

Shipmondo quote field Freight quote option field
product_code External Service Code. Also used to find the Business Central shipping agent and service: it must match External Shipping Agent ID in Map Shipping Agents.
carrier_code External Agent Id (also Carrier Name if no carrier name is returned)
carrier_name Carrier Name
description Service Name
price_before_vat Price
list_rate / rate_cost List Rate / Rate Cost
currency_code Currency Code
delivery_days / estimated_delivery_date / transit_time Delivery Days / Estimated Delivery Date / Transit Time

Fields that Shipmondo does not return stay blank. When you select an option, the shipping agent and service are set on the document. On sales orders you can then add a freight line with the Freight Quote Item No.: the price is converted to the order currency, and any Markup % and Line Discount % from the freight quote rules are applied.

Data returned and troubleshooting

Two values come back from Shipmondo and are written to the waybill:

Shipmondo response field Waybill field
id (shipment ID) Pickup No.
pkg_no (package number) Waybill Tracking No.

The tracking number is also copied to Package Tracking No. on the related posted sales shipments. Labels are not stored in Business Central; they are printed by Shipmondo.

Symptom Check
Nothing is sent when packing is finished Shipmondo is on in Shipping Manager Setup, SyncWaybill is on, and Send Waybill holds the flow URL
Error: a field must have a value All four credential fields and Shipmondo Environment are filled in on the Connector Card
Send Shipment to Shipmondo failed Open the Integration Error Log for Shipmondo's message. Common causes: wrong product or service codes in Map Shipping Agents (see How To Map Shipping Agent and Shipping Services), or wrong API credentials.
No error e-mail received The current flow does not send e-mails. Check the Integration Error Log on the connector.
Shipments land in the wrong Shipmondo environment The flow in Send Waybill matches Shipmondo Environment
Label not printed Hostname, Printer and Label Format on the packing station match the Shipmondo portal, and the waybill has a packing station. See How to integrate with the Shipmondo Print Client.
Wrong weight or size in Shipmondo Weight unit is KG (or grams) and dimension unit is M (or centimetres) on the waybill lines
Freight quote option selected, but no shipping agent is set The option's product code must match External Shipping Agent ID on a line in Map Shipping Agents