Webshipper Connector – Setup and Field Mapping

Prev Next

Overview

When a waybill in Shipping Manager is ready to send, the Webshipper Shipping Connector creates a shipment in Webshipper through the Webshipper API (v2). Webshipper returns the shipment with tracking links, and Business Central stores the first tracking number on the waybill. Labels are printed by Webshipper on the printer client you choose per packing station.

The connector has two parts:

  • Business Central app: Webshipper Shipping Connector (version 28.0). It depends on Shipping Manager, Abakion Manager Foundation and Abakion App Manager Core.
  • Power Automate solution: Webshipper Shipping Connector (SMWebshipper, version 1.0.0.3). It contains one flow, Webshipper - SendWaybill, which you call from Business Central.

The connector does not support freight quotes.

Prerequisites

  • Shipping Manager is installed and set up, including shipping agents, services and packing stations.
  • A Webshipper account with an API token. You need the account name (the first part of your Webshipper URL, as in account.api.webshipper.io).
  • The Webshipper carrier IDs or shipping rate IDs you want to use, and the printer client ID for each packing station.
  • An app registration in Microsoft Entra ID with access to the Business Central API (BC Client ID and BC Client Secret).
  • A Power Automate environment where you can import a solution and use the premium HTTP trigger.

Setup

Set up the connector in this order. Each step builds on the one before.

  1. Activate the app. After installation, run the assisted setup Activate Webshipper Shipping Connector and start the trial or enter your license. The last page links to the free Webshipper Power Automate app.
  2. Enable the connector. Open Shipping Manager Setup and turn on Webshipper in the Connectors section.
  3. Get Webshipper credentials. In Webshipper, create an API token and note your account name. Note the IDs of the carriers or shipping rates you will use, and the printer client IDs. See Set Up the Webshipper Connector Card.
  4. Get Business Central API credentials. Create or reuse an Entra ID app registration with access to the Business Central API. Note 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 it and turn on Webshipper - SendWaybill. Copy the HTTP POST URL from the flow trigger.
  6. Create the connector. Open Connectors, create a new card and fill in the fields below. Enter Webshipper Account before Webshipper Token (see Setup pitfalls).
Field What to enter
ID, Description A code and name for the connector.
Type Webshipper Connector. Shipping Manager is set as manager type automatically.
Email for Errormessages Who gets an email when a waybill fails. Leave blank for no email.
SyncWaybill Turn on. Without it, waybills are not sent to Webshipper.
URL SendWaybill The HTTP POST URL from step 5.
BC Client Id Client ID of the Entra ID app registration. Required.
BC Client Secret Client secret of the Entra ID app registration. Required.
Webshipper Account Your Webshipper account name, without ".api.webshipper.io". Required.
Webshipper Token Your Webshipper API token. Required.
  1. Map shipping agents. On the connector, open the shipping agent mapping and add a line per shipping agent and service.
Field What to enter
Shipping Agent Code, Shipping Agent Service Code The Business Central shipping agent and service.
External Shipping Agent ID The Webshipper service code for the shipment.
Webshipper Type Carrier or ShippingRates. Decides whether the shipment is linked to a carrier or a shipping rate in Webshipper.
Webshipper TypeId The ID of that carrier or shipping rate in Webshipper.

Map package types to Webshipper colli types in Package Type Mapping: set External Key to the Webshipper colli type.

  1. Set up packing stations. On each Packing Station, enter PrintID: the ID of the Webshipper printer client that should print the labels.
  2. Test. Send a waybill for a test shipping agent and check that the shipment appears in Webshipper with the right carrier or shipping rate. The Test BC Connection action is not available for this connector type.

Validation before sending

When a waybill becomes ready to send, the app checks the setup before it calls the flow. If a check fails, the status change is stopped with one of these errors:

  • Shipping Manager Setup is missing.
  • Webshipper Connector is not activated on Shipping Manager Setup.
  • Field must have a value in Connector ID, it cannot be blank. This applies to BC Client Id (shown as "Webshipper Username"), BC Client Secret (shown as "Webshipper Password"), Webshipper Token and Webshipper Account.

The app does not check the shipping agent mapping, the packing station or the flow URL.

Setup pitfalls

  • Entering or changing Webshipper Account clears the stored Webshipper Token. Always enter the Account first and the Token last. If you change the Account later, enter the Token again.
  • The flow trigger accepts any caller that has the URL. Treat URL SendWaybill as a secret.

How a waybill is sent

A waybill is sent automatically when its status changes to Packing Finished. A successful run ends with status Shipping Agent Ordered.

  1. The waybill status changes to Packing Finished, and the integration status becomes Ready to send.
  2. If the waybill's shipping connector is a Webshipper connector with SyncWaybill on, the app runs the validation above and calls the flow URL with the waybill number, credentials and Webshipper account.
  3. The flow reads the waybill, its lines and its customs lines from Business Central.
  4. The flow reads the shipping agent mapping for the waybill's connector, shipping agent and service, to get Webshipper Type and Webshipper TypeId.
  5. If the waybill has a packing station, the flow reads its PrintID.
  6. The flow builds the shipment and creates it in Webshipper. If the waybill has customs lines, customs lines are added to the packages.
  7. The flow writes the first tracking number from Webshipper to Waybill Tracking No. and clears Pickup No.
  8. The flow writes an entry to the waybill's Activity Log ("Waybill send to Webshipper") with the Webshipper response.
  9. The flow marks the waybill as successfully sent. The status changes to Shipping Agent Ordered.

If any step from 3 to 9 fails, the flow sets the integration status to Error and emails the recipients in Email for Errormessages.

Step that failed Error text in Business Central
Any step Error try send waybill to Webshipper. The details hold the response of the failed call, for example Webshipper's validation errors.
Reading the waybill (step 3) No error is written to the waybill and no email is sent. Check the flow run history.

The error email has the subject "Waybill No. failed to send (environment)". It lists each failed action and links to the flow run and the waybill.

Field mapping

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

Shipment

Webshipper field BC source Notes
reference Waybill No.
service_code External Shipping Agent ID (shipping agent mapping) Found by the waybill's connector, shipping agent and service.
relationships › carrier Webshipper TypeId (shipping agent mapping) When Webshipper Type is Carrier.
relationships › shipping_rate Webshipper TypeId (shipping agent mapping) When Webshipper Type is ShippingRates.
drop_point › drop_point_id Pickup Point Only sent for shipments without customs lines.
comment Fixed value: empty

External Shipping Agent Service Code is not sent.

Receiver (delivery_address)

Webshipper field BC source Notes
company_name Name Name 2 is not sent.
address_1 Address
address_2 Address 2
zip Post Code
city City
country_code Country/Region Code
phone Phone No.
email e-mail
att_contact Contact
address_type Fixed value: recipient

County is not sent.

Sender (sender_address)

Webshipper field BC source Notes
company_name Sender Name Sender Name 2 is not sent.
address_1 Sender Address
address_2 Sender Address 2
zip Sender Post Code
city Sender City
country_code Sender Country/Region Code
phone Sender Phone No.
email Sender e-mail
att_contact Sender Contact
address_type Fixed value: recipient Same value as for the receiver.

Parcels (packages)

Each waybill line is sent as one package.

Webshipper field BC source Notes / conversion
colli_type External Key (Package Type Mapping) Found by shipping agent, connector and the line's Package Type.
weight Gross Weight (waybill line) No conversion.
weight_unit Weight Unit of Measure Sent in lower case, for example kg.
dimensions › package_id Package No.
dimensions › length, width, height Length, Width, Height (waybill line) No conversion.
dimensions › unit Dimension Unit of Measure Sent in lower case, for example cm.

Customs

Customs lines are sent only when the waybill has customs lines of type Line with a Ship Quantity above 0. Each customs line is split over the packages: every package gets Ship Quantity ÷ No. of Colli, and the last package also gets the remainder. Customs lines are matched to packages by position, so No. of Colli must equal the number of waybill lines.

Webshipper field (customs_lines) BC source Notes / conversion
sku Item No.
description Description
quantity Ship Quantity Split over the packages as described above.
tarif_number Tariff No.
country_of_origin Country of Origin
unit_price Ship Amount ÷ Ship Quantity
vat_percent Fixed value 0
currency Currency Code
weight Ship Gross Weight ÷ the quantity in this package
weight_unit Weight Unit of Measure of the waybill lines Lower case. Taken from the last waybill line.

Tariff Description, Ship Net Weight, Reason for Export and VAT numbers are not sent.

Printing

Webshipper field BC source Notes
relationships › printer_client PrintID (packing station) Read from the waybill's packing station.

Data returned and troubleshooting

Webshipper returns the created shipment. Only the first tracking number is used in Business Central.

Webshipper response field Waybill field Notes
tracking_links › number (first) Waybill Tracking No. (header) Tracking numbers for other packages are not stored.
(none) Pickup No. (header) Cleared on every successful send.
Whole response Activity Log Entry "Waybill send to Webshipper".

The waybill lines do not get tracking numbers. When Waybill Tracking No. changes, Shipping Manager copies it to Package Tracking No. on the posted sales shipments linked to the waybill. Labels are printed by Webshipper and are not stored in Business Central.

Symptom Check
Error when setting Packing Finished Read the error. Webshipper must be on in Shipping Manager Setup, and BC Client Id, BC Client Secret, Webshipper Account and Webshipper Token must be filled. "Webshipper Username" and "Webshipper Password" in the error mean BC Client Id and BC Client Secret.
"Webshipper Token must have a value" right after setup The Token was cleared when you entered the Account. Enter the Token again.
Status stays Packing Finished, no error, nothing in the Activity Log SyncWaybill is off, URL SendWaybill is wrong, or the flow is turned off. Check the flow run history.
Integration status Error, "Error try send waybill to Webshipper" Open the error details for Webshipper's response. Check the shipping agent mapping (External Shipping Agent ID, Webshipper Type, Webshipper TypeId), addresses and package types.
"Unauthorized" from Webshipper Check Webshipper Account and Webshipper Token. See Set Up the Webshipper Connector Card.
"Unauthorized" from Business Central Check BC Client Id, BC Client Secret and the app registration's permissions in Business Central. See How to get BC Client ID and BC Client Secret for Connector.
Shipment created with the wrong carrier or rate Check Webshipper Type and Webshipper TypeId on the mapping line for the waybill's shipping agent and service.
Label printed on the wrong printer, or not at all Check PrintID on the packing station, and that the waybill has a packing station.
Pickup point missing in Webshipper The waybill has customs lines. The pickup point is only sent for shipments without customs.
Customs quantities wrong or missing on some packages No. of Colli must equal the number of waybill lines.