Sign in

nShift Help Center

XML file specification

Avatar
Malene Tidemann
Updated

Sections in this article:

 

Introduction

XML file described in this document can be used as a data carrier together with several integration methods.

In case of integrity errors, such as missing XML tags, the file will be ignored. If there are errors in the variable data, such as missing information and/or invalid values, the order will be marked as invalid in nShift Delivery. 

Normally, the following XML declaration is used:

<?xml version="1.0" encoding="ISO-8859-1"?>

If Unicode is used, one of following options is valid, depending on type:

<?xml version="1.0" encoding="UTF-8"?>
<?xml version="1.0" encoding="UTF-16"?>


There are characters that can occur in variable data that need to be entered so that the XML parser can interpret them correctly:

  • & is entered as &amp;
  • < is entered as &lt;
  • > is entered as &gt;
  • ' is entered as &apos;
  • " is entered as &quot;

For valid values, please refer to the value reference guide and the example files.



Sender

The sender element contains sender's information and its occurrence is not always mandatory in a file as sender's information can be predefined in nShift Delivery. If this is the case, only a referral is needed in the order file, pointing to a sender's so-called Quick ID value. This referral is done in the shipment element. In cases where there are several senders and when a static structure is not possible, the information about the sender must be supplied in the order file.

 

The sender element consists of <sender sndid="..."> where ... is to be replaced with an attribute of your choice with any data type and length. The element must end with </sender>. Values are supplied as <val n="value name"</val>. An index of valid values can be found in the Value reference guide. Partner (carrier) information must also be supplied in those cases senders are not predefined in nShift Delivery. This is done by a nested partner element with an attribute that specifies the carrier and the element's mandatory values. The index of valid partner attributes can be found in the Help > Code lists > Services menu in nShift Delivery.

 

Example

<sender sndid="1">
   <val n="name">The Sender</val>
   <val n="address1">Testvägen 1</val>
   <val n="address2">Ingång C</val>
   <val n="zipcode">41118</val>
   <val n="city">GÖTEBORG</val>
   <val n="country">SE</val>
   <val n="contact">Sender's Contact</val>
   <val n="phone">031-000 00 00</val>
   <val n="email">contact@sender.xyz</val>
   <val n="sms">0700-00 00 00</val>
   <partner parid="PLAB">
      <val n="custno">0123465782</val>
   </partner>
</sender>



Receiver

The receiver element contains receiver's information and its occurrence in a file is mandatory. The receiver element consists of <receiver rcvid="..."> where ... is to be replaced with an attribute value of your choice with any data type and length. The element must end with </receiver>. Values are supplied as <val n="value name">...</val>. An index of valid values can be found in the Value reference guide.

In cases where the shipment contains addon services that demand further information (for example, receiver pays, which requires the receiver's customer for the carrier), the partner information must be supplied as well. This is done by a nested partner element with an attribute that specifies the carrier and the element's mandatory values. An index of valid partner attributes can be found in the Help > Code lists > Services menu in nShift Delivery.

 

Example

<receiver rcvid="Customer_001">
   <val n="name">The Receiver</val>
   <val n="address1">Kundvägen 10A</val>
   <val n="address2">2 trappor</val>
   <val n="zipcode">41480</val>
   <val n="city">GÖTEBORG</val>
   <val n="country">SE</val>
   <val n="contact">Contact person</val>
   <val n="phone">031-000 00 00</val>
   <val n="email">contact@receiver.xyz</val>
   <val n="sms">0700-00 00 00</val>
</receiver>

 

 

Party

The party element contains a neutral party’s information and its occurrence is optional. The party element consists of <party ptyid="..."> where ... is to be replaced with an attribute value of your choice with any data type and length. The element must end with </party>. Values are supplied as <val n="value name">...</val>. An index of valid values can be found in the Value reference guide. In cases where the shipment contains addon services that demand further information (for example, other payer, which requires the party’s carrier customer number), the partner information must be supplied as well. This is done by a nested partner element with an attribute that specifies the carrier and the element's mandatory values. An index of valid partner attributes can be found in Help > Code lists > Services menu in nShift Delivery.

 

Example

<party ptyid="Party_001">
   <val n="name">Freight Payer Company</val>
   <val n="address1">Freight Avenue 10</val>
   <val n="address2">5th floor</val>
   <val n="zipcode">41480</val>
   <val n="city">GÖTEBORG</val>
   <val n="country">SE</val>
   <val n="contact">Some person</val>
   <val n="phone">031-000 00 00</val>
   <val n="email">any@freightpayer.se</val>
   <val n="sms">0700-00 00 00</val>
</party>

 

 

Shipment

The shipment element defines the shipment itself and its presence is mandatory. Sender, receiver, delivery terms, service type and addons are defined in this element. The shipment element consists of <shipment orderno="..."> where ... is to be replaced with an attribute value of your choice with any data type and length. This attribute is not printed on shipment documents, it is unique for every shipment in a file and is searchable in nShift Delivery.

The information about the sender and receiver is supplied as <val n="from">...</val> and <val n="to">...</val>. These values refer to the sender's sndid and the receiver's rcvid attributes as mentioned in our examples earlier. Remember that sender information can also be predefined in nShift Delivery which makes the sender element obsolete. If this is the case, the value from should refer to the sender's quick ID in nShift Delivery.

Additional values are supplied as <val n="value name">...</val>. An index of valid values can be found in the Value reference guide. The element must end with </shipment>.

Prepared shipments, which are shipments originating from nShift Checkout, can be completed by using XML-file. In that case, the shipment element must contain the prepareid attribute, <shipment orderno="..." prepareid=”...”>. Once a shipment is completed, the prepare ID is deleted. However, if there is a need to keep the prepare ID for later use, it can be done by using the keeppreparedshipment attribute, <shipment orderno="..." prepareid=”...” keeppreparedshipment=”yes”>.

 

Service

This element contains the carrier's service code and its presence is mandatory. It is supplied as a nested element under shipment as <service srvid="..." where ... corresponds to service code. An index of valid codes can be found in Help > Code lists > Services (ERP-connection XML) menu in nShift Delivery.

The element must end with </service>.

 

Addon services

As mentioned earlier, addon services such as Cash On Delivery and Receiver payment to name a few can be supplied in this element. Addons are defined as nested elements to the service element as <addon adnid="..."> where ... corresponds to the addon code. An index of valid addon codes can be found in the Help > Code lists > Services (ERP-connection XML) menu in the system.

Addons may require additional information in order to be valid. For instance, Cash On Delivery requires an amount and a payment reference. An index of valid values can be found in the Value reference guide. The element must end with </addon>.

 

Container

The container element defines contents of the shipment, for example, number of parcels, weight and volume. This element is also nested in the shipment element. Values are supplied as <val n="value name">...</val>. An index of valid values can be found in the Value reference guide.


Parcel information can be defined in several different ways:

<container type="parcel"> defines information for each parcel individually.

<container type="parcel" measure="totals"> defines information for an entire row of parcels.

<container type="parcel" partorderno="..."> defines an order number for the parcel row. Any value.

<container type="totals" measure="totals"> defines information for the entire shipment.

 

Important: Use only one parcel definition type per shipment.

 

Example - per parcel

<container type="parcel">
   <val n="copies">2</val>
   <val n="weight">10</val>
</container>

Shipment contains two parcels and the total weight is 20 kg (2 parcels x 10 kg).

 

Example - per parcel row

<container type="parcel" measure="totals">
<val n="copies">2</val>
<val n="weight">10</val>
</container>

Shipment contains two parcels and the total weight is 10 kg. The individual parcel weight is only assumed to be 5 kg each. Please note that the assumed individual parcel weight will not be printed on shipping documents.

 

Example - a shipment element

<shipment orderno="Ordernumber_1">
   <val n="from">1</val>
   <val n="to"> </val>
   <val n="reference">Shipment reference</val>
   <val n="freetext1">Text of your choice</val>
   <service srvid="P15">
   </service>
      <container type="parcel">
         <val n="copies">1</val>
         <val n="weight">10</val>
         <val n="contents">Stuff</val>
      </container>
</shipment>

 

Customs declaration documents

This element contains information about customs declaration documents. It is supplied as a nested element under shipment as <customsdeclaration documents="..."> where ... corresponds to the document type.

If using multiple attribute values, separate them with a pipe character (|).

  • PROFORMA = Proforma / commercial invoice
  • EDOC = ED document
  • PROFORMAPLABEDI = Proforma / commercial invoice by EDI and a printed copy (PostNord Sweden only)
  • PROFORMATNT = Proforma / commercial invoice for TNT
  • NOTETNT = Note for TNT
  • PLT = Customs information via EDI only
  • PNLWAYBILLEDI = I will send a separate customs declaration (EDI) (Bring only)
  • BRINGEDI = I will send a separate customs declaration and VAT on e-commerce (EDI) (Bring only)
  • CN22 = CN22POSTNORD
  • CN22DKPBREVINC = CN22 for Postnord DK Tracked
  • CN22INC = CN22 for Deutsche Post, PostNord Brev and Direct Link
  • CN23 = CN23POSTNORD
  • CN23MULTPDK = CN23 for Postnord DK Tracked
  • CN23PDK = CN23 for PostNord DK EMS International Express
  • CN23ATTACHED = Commercial invoice attached for PostNord DK EMS International Express
  • CN22POSTI = CN22 for Posti
  • CN23POSTI = CN23 for Posti
  • PROFORMAUPS = Proforma / commercial invoice for UPS
  • FEDEXP = Commercial Invoice for FEDEX
  • TRADEINVOICEPDK = Customs declaration for PostNord Denmark
  • DHLROADSTD = DHL Customs Standard
  • DHLAIR = DHL Express

Additional values are supplied as <val n="value name">...</val>. An index of valid values can be found in the Value reference guide. The element must end with </customsdeclaration>.


Example - customs declaration

<customsdeclaration documents="|PROFORMA|">
   <val n="senderorgno">12121212</val>
   <val n="parcelcount">1</val>
   <val n="invoicetype">PROFORMA</val>
   <val n="customsunit">SEK</val>
   <val n="impexptype">OTHER</val>
   <line measure="totals">
      <val n="statno">12121212</val>
      <val n="customsvalue">111.0</val>
      <val n="contents">Things</val>
      <val n="quantity">1</val>
      <val n="sourcecountry">SE</val>
   </line>
</customsdeclaration>

 

You can generate a sample file from your shipment history. Please refer to Generate integration file from history.

 

 

Additional elements

There are several non-mandatory elements that can be supplied if extended functions are desired.

 

Meta

This element is usually inserted first in a file, directly after the declaration of the root element. The meta element can contain printer mapping, mapping to a certain print favorite etc. Values are supplied as <val n="value name">...</val>. An index of valid values can be found in the Value reference guide.

 

Pre-notification by email

This service is declared as part of a standalone element <ufonline> nested under the shipment element. Values are supplied as <val n="value name">...>/val>. An index of valid values can be found in Value reference guide.

Example

<ufonline>
   <option optid="enot">
      <val n="sendemail">yes</val>
      <val n="from">customerservice@mycompany.xyz</val>
      <val n="to">someone@otherside.xyz</val>
      <val n="message">Your package is on the way!</val>
   </option>
</ufonline>


The element must end with </ufonline>.

 

Link to Print

This service is declared as part of a standalone element <ufonline> nested under the shipment element. The declaration of the shipment element can also contain the attribute linkprintkey which is a unique value of any data type and length. This is used if it is desirable to know what the final link would look like. In this example, we will use aFg3rA as a key which would give us a link like this:

 https://www.unifaunonline.com/ext.uo.se.se.linkprint?key=<user-ID>&>job=aFg3rA&mode=normal

Due to the key being visible in the link, it is important that you do not use simple keys such as number sequence or similar. The recipient could change the link and print other recipient's shipping documents. Do not use empty spaces or underline characters in the link.

If linkprintkey is not supplied the system will automatically generate one.

 

Example

<ufonline>
   <option optid="lnkprtn">
      <val n="sendemail">yes</val>
      <val n="from">customerservice@mycompany.xyz</val>
      <val n="to">someone@otherside.xyz</val>
      <val n="message">Here is the link to your shipping documents!</val>
   </option>
</ufonline>

 

Consolidated shipment

This service permits continuous printing of shipping labels while the EDI message is held until the shipment is closed. A typical use case is if you have multiple orders to a certain receiver during the day and you wish to consolidate these into one single shipment. This service is declared as part of a standalone element <ufonline> nested under the shipment element.

Example

<ufonline>
   <option optid="CONSOLIDATE">
   </option>
</ufonline>

The consolidated shipment service requires the mergeid attribute in shipment element tag.

 

Example

<shipment orderno="Ordernummer_1" mergeid="MRG001">

Mergeid can be an alphanumeric value of your choice and should be unique for each shipment. Do not use empty spaces or underline characters. Consolidated shipments need to be closed, either manually in nShift Delivery or by supplying a closing XML file containing a control element directly under the root element.

 

Example

<control>
   <close>
      <val n="mergeid">MRG001</val>
   </close>
</control>


Closing a consolidated shipment triggers waybill and eventual customs declaration documents printout to preset laser printer if no printer is specified in the <val n="printer"> tag.

 

Example files

Download the example files.

Related articles