Upgrading to Shipping Guide API 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
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.
If you are already using Mybring authentication, the same API key can be reused. If not, steps for getting a key and description of headers can be found on the general API Getting Started / Authentication page.
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.
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.
Removed in Request
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.
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.
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:
Changed in response
ProductId element is renamed to
CustomerNumber attribute is changed to being an element.
ProductCodeInProductionSystemelement is renamed to
UpsSpecificEdiParametersType elements are grouped inside a
Edi element and the names are shortened, i.e.
"SpecificEdiParametersType" is removed from the names.
Price is renamed to
ListPrice and that element,
PipSpecificPrice are grouped inside a
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.
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
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.
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.