Upgrading to version 2.0

This is a short summary of the differences between version 1.xx and 2.0 of the Shipping Guide API and will help you migrate to version 2.0 of the API.

We recommend always updating to the latest version and to do it at your earliest convenience. Upgrading to the latest version maximizes the time between upgrades.

The older 1.xx versions will become deprecated and shut down some time in the future.

SOAP and JSON interface

What we have changed

This section describes the main changes we have done to both the SOAP and the JSON interface

Authentication is mandatory

Authentication is mandatory. If we know you better, we will be in better position to notify you about new features in future and also about changes to API in general. It is similar to authentication process to what we had earlier. What is changed, we do not need to send X-Bring-Client-URL in headers now since you are already authenticated.

If you are a new user, Signup here. After login into Mybring, the API key will be generated by default. You will find your API key here

Note: If you are already using Mybring authentication, same API key could be reused.

Restructured error response

In version 1 of the Shipping Guide API client and server error responses are mainly a HTML document describing what went wrong, but in some cases trace messages are used. In version 2.0 this is changed to be easier to parse. You can read more about the new format of the errors in Handle API errors and warnings.

Introduced warnings

We have also introduced warnings on product level in Shipping guide response. Warnings are send out when Shipping guide is able to validate the request but missed some part of response for example Price or lead time due to unavailability of external systems. Ideally clients should not parse these warning codes for any logic as they are bound to change. These are supposed to be treated as informational data. Warning codes are documented in xsd as well.

Trace messages are disabled by default for SOAP

Trace messages are now disabled by default and will not be send out in response. If in case you explicitly need trace messages then it has to be passed explicitly in request.

Query params for REST endpoint

Some of the query params of REST endpoint has slightly changed its name and they are not in camel case anymore. Meaning and functionality remains the same.

SOAP interface

What we have removed in Request

Request properties

The tag is no longer available, as we have moved all its tags up to be parent tag, ShippingGuideRequest

WithPackageDetails tag is no longer available, as we have discontinued package based shipping guide request.

TimeSlots tag

The tag is removed and no longer available.

Consignment and Packages tags

These tags are no longer available. From schema version 9, we introduced Consignments tag which consists of all of these tags.

In shipping guide, every request can contain one or many consignments with shipments details, product ids, and package details (packages can be one or many).

So in Shipping guide 2.0, we have generalised it, and removed all the individual tags which are already part of Consignments tag.

Unit code for dimension in Consignments tag

unitCode is removed from the measurements LxWxH. The unit used is standard metric measurements units.

  • Length, width, and height can only be requested in centimeters
  • Weight can only be requested in grams.
  • Volume can only be requested in dm3.

Consignment tag in Consignments tag

This tag is just unwrapped, all the tags are still present, but not grouped. They are now part of the parent tag. Refer schema of Shipping Guide 2.0.

What we have changed in Request

ConsignmentId attribute in Consignments tag

The attribute is renamed to Id only.

AdditionalServiceId tag under the AdditionalService tag

The attribute is renamed to Id only.

ProductIds tag and its children

The ProductIds tag is now called Products.

For each previous ProductId tag, we now have a new tag called Product. All the previous attributes of the ProductId tag, are now moved to separate nested tags under the Product tag.

The ProductId tag is now in a tag called Id.

The customerNumber attribute is now moved to a separate tag called CustomerNumber.

The autoSelectCustomerNumber attribute is now moved to a separate tag called AutoSelectCustomerNumber.

The whichPartyIsPayer attribute is now moves to a separate tag called Payer with these valid values:

  • SENDER
  • RECEIVER
  • THIRD_PARTY

What we have changed in response

ProductId

ProductId element is renamed to Id.

CustomerNumber

CustomerNumber attribute is changed to being an element.

ProductCodeInProductionSystem

ProductCodeInProductionSystemelement is renamed to ProductionCode.

EDI information

CourierSpecificEdiParameters, QuickpackSpecificEdiParametersType and UpsSpecificEdiParametersType elements are grouped inside a Edi element and the names are shortened, i.e. "SpecificEdiParametersType" is removed from the names.

Price information

Price is renamed to ListPrice and that element, NetPrice and PipSpecificPrice are grouped inside a Price element.

What we have removed in Response

Packages and Consignment response tags

These tags are removed for we don't support individual package level and consignment level requests anymore.

Consignments response tag

Trace messages and packages are removed, we have generalised a the response a lot, for better response format and parsing.

Products tag

This tag is has all the existing fields with few more added fields. Like Error and warning tags, for better error, handling. For more information, kindly refer the schema Shipping Guide 2.0

JSON interface

The overall response of all the three REST APIs is same, and conforms Shipping Guide 2.0 schema. So, response tags of REST API follow the previous section as well.

What we have removed

Price adjustment

We do not support price adjustment in Shipping Guide 2.0. The pricing model is very simple now. It should be very easy to do price adjustment at client side.