EDI XML format

This is the XML format used when creating shipments in the Leaps system via the API.

The EDI XML has the following structure:

^{<header> <authentication> ... </authentication> <consignmentlist> <consignment> <bookingmethod> ... </bookingmethod> <part role=""> ... </part> <pdinstructions> ... </pdinstructions> <transportservice> ... </transportservice> <references> ... </references> <paymentinstructions> ... </paymentinstructions> <goodsitem> ... </goodsitem> <file>...</file>
<othercharges>...</othercharges> </consignment> </consignmentlist> </header>}

Values

Dates are specified as YYYY-MM-DD. Time is specified as HH:MM. Date+time is specified as YYYY-MM-DD HH:MM.

Decimal values are specified using . (full stop) as decimal point. No thousand-separator is allowed.

All text must be specified in UTF-8.

Dimensions are specified in meters. Weight is specified in kgs. Volume is specified in m3.

NOTICE that XML element names are casesensitive, so f.ex. "<OtherCharge>" is not the same as "<othercharge>".

Header

The test attribute may be set to 1 to make this a test booking. Default value is 0.

^{<header test="1">}

Authentication

The <authentication> element describes who it is that is trying to book a shipment. It contains the following elements.

^{<username>jimbo</username> <password>Test1234</password> <companyid>DKTESTDK</companyid> <datetime>2015-02-19 18:45:00</datetime> <xmlversion>1</xmlversion>}

All elements are required.

Booking method

The <bookingmethod> element contains the following elements:

^{<template>DHL test</template> <autobook>yes</autobook> <label>yes</label> <labeltype>LABEL</labeltype> <errormail>my@email.com</errormail> <returnservice>no</returnservice>}

The <template> element is required, and refers to the name of a template defined for the portal.

The <autobook> element is optional and can be yes or no. Default is no. If set to yes then the shipment will be booked, otherwise it will be saved in “Incomplete bookings”.

The <label> element is optional and can be yes or no. Default is no. If set to yes then a label will be included in the reply.

The <errormail> address is optional and is used whenever the EDI booking goes wrong. An email is then sent to the address, containing the XML.

<labeltype> determines the format of the label. Values can be either A5 or LABEL (default). The element is ignored if the <label> element isn't set to yes.

The <returnservice> element determines if a return shipment should be booked; if specified it overrides the setting in the template. It only works with DHL and TNT shipments. The same product will be used for the return shipment as for the actual shipment. If the return shipment cannot be booked then the actual shipment will still be booked and a warning will be returned.

Part

The <part> elements describes the consignor and consignee etc, so there may be multiple <part> elements, for 'consignor', 'consignee', 'pickup', 'delivery', 'ordering', 'importer', 'exporter' or 'notify'. Which is which is determined by the role attribute, eg.:

^{<part role="consignor">}

The <part> elements are optional, if either isn't specified then the consignor/consignee/pickup/delivery/ordering/importer/exporter/notify address from the template will be used.

The <part> element may hold these elements, unless role is 'ordering':

^{<address> <id></id> <name>DK Shipping</name> <address1>Vesterbrogade 123</address1> <address2></address2> <postcode>2300</postcode> <city>Copenhagen</city> <state></state> <countrycode>DK</countrycode> <unloc>DKCOP</unloc>
<vat_no>VATNO</vat_no>
<eori_no>EORINO</eori_no> </address> <communication> <contactperson>Ronald Reagan</contactperson> <phone>12345678</phone> <mobile>20123456</mobile> <email>test@test.dk</email> </communication>}

If role is 'ordering' then only these elements are allowed and are required:

^{<address> <id>MYORDERINGID</id> </address>}

If <id> is specified and refers to the ID of a valid address in the addressbook, then the rest of the address in the EDI XML will be ignored (with the exception of <contactperson> for consignor), and the address will be taken from the addressbook. Notice, it must be the ID, not the GID, of the address in the addressbook.

PDInstructions

This element describes pickup and delivery. It may contain the following elements:

^{<pickup> <pdate>2015-06-30</pdate> <earliest>10:00</earliest> <latest>15:30</latest> <pinstructions>call before pickup</pinstructions> <pickupbycarrier>no</pickupbycarrier> </pickup> <delivery> <ddate>2015-07-04</ddate> <dinstructions>call before delivery</dinstructions> </delivery>}

The only element which isn't required is <dinstructions>.

The <pinstructions> and <dinstructions> elements are included then the shipment is sent to certain carriers eg. TNT and DHL.

If the <pickupbycarrier> element is specified then it overrides the setting in the template.

Transport service

The <transportservice> element contains the following elements:

^{<deliverytype>DD</deliverytype> <todcountry>SE</todcountry> <todcity>Malmø</todcity> <reliabletoduty>no</reliabletoduty> <value>123</value> <currency>EUR</currency> <warning>yes</warning>}

<reliabletoduty> must be yes or no. If yes then <currency> must be one of the currencies recognised by the system, and <value> must be greater than 0. If <value> is 0 or not specified, then the booking will be saved with in “incomplete bookings”.

If <todcountry> is set it must contain the 2 letter country code for the country.

<deliverytype> must be one of: DD, DA, DP, AD, AA, AP, PD, PA, PP, DT, TD, TT.

<warning> determines if a warning should be returned if there is dangerous goods, but no declaration is attached. Can be yes or no, default is yes.

References

The <references> element may contain the following elements:

^{<sendersreference>4234234</sendersreference> <receiversreference>34523634562</receiversreference> <cargocontrolno>123123123</cargocontrolno> <carriertrackingno>234234234</carriertrackingno> <hawbno>345354</hawbno> <invoiceno>456546</invoiceno> <packageid>567567</packageid> <productioncode>678678</productioncode> <projectno>789789</projectno> <purchaseorderno>895954</purchaseorderno> <senderref>923423</senderref> <shipmentreferenceno>a2342123</shipmentreferenceno> <slinoref>3300004123</slinoref> <bookingconfirmnumber>9543467844</bookingconfirmnumber> <awbno>3467245325363</awbno>}

<sendersreference> is required.

<slinoref> must be a number.

You may only specify <awbno> if the product isn't a “carrierdirect” product.

<bookingconfirmnumber> is only used for certain FedEx shipments where it is required; the number must be allocated by FedEx. For other shipments it is ignored.

Payment instructions

The <paymentinstructions> element holds the following:

^{<incoterms>DAP</incoterms> <accountno>567567457</accountno>
<generateinvoice>yes</generateinvoice>}

<incoterms> is required and must be one of the following: EXW, FCA, CPT, CIP, DAT, DAP, FAS, FOB, CFR, CIF, DDU, DDP.

<accountno> is required if <incoterms> is set to EXW.

<generateinvoice> can be yes or no (default), and determines if the carrier should be asked to generate an invoice PDF.

Goods item

There may be multiple <goodsitem> elements. Each may hold these elements:

^{<noofpackages>1</noofpackages> <width>40</width> <length>60</length> <height>50</height> <weight>40</weight> <volume>0.12</volume> <packagetype>Pallet</packagetype> <packagecode>PLT</packagecode> <goodsdescription>Donuts for Homer</goodsdescription> <shippingmark>1044651</shippingmark> <dangerous>no</dangerous> <origincountry>DE</origincountry> <itemlevel> <qty></qty> <name></name> <hscode></hscode> <article></article> <unitprice></unitprice> <currency></currency> <origincountry>DE</origincountry> </itemlevel>}

<width>, <height>, <length> is per package.

Starting from sometime 2015-12-01 <volume> should be specified as total for the <goodsitem>.

<weight> and <volume> are totals for the <goodsitem>.

<noofpackages> is treated as an integer.

If no <goodsitem> elements are included, goods item specified in the template will not be used - instead you will get an error.

<noofpackages>, <weight> and <goodsdescription> are required.

Either <packagetype> or <packagecode> must be specified.

Either <volume> or all of <length>, <width>, <height> must be specified.

There may be multiple <itemlevel>, see below.

<volume> is in cubic meters. <weight> is in kilograms. Dimensions are in centimeters.

<origincountry> may be specified either in <itemlevel> or in <goodsitem>. If multiple countries are specified in <itemlevel> then you should also specify a country in <goodsitem>.

<dangerous> can be either yes or no or a code from the list of dangerous goods. Default is no. The possible codes are listed below, in the section “Dangerous goods”. If a code is specified then the <goodsdescription> element will be overwritten. An example could be:

^{<dangerous>930</dangerous>}

Item level

<itemlevel> is optional, there may be any number of <itemlevel>.

<qty> is the number of items of the given type.

If <origincountry> isn't specified for the <itemlevel> then it will be taken from the <origincountry> element in the <goodsitem>.

If <goodsitem> specifies <noofpackages> = 5 and an <itemlevel> specifies <qty> = 4 then the total shipment contains 5*4=20 items of the specified type.

Package types / codes

The following values are allowed for <packagetype>:

20' Flat bed, 20' Flat collapsible, 20' Flatrack, 20' General purpose, 20' High cube, 20' Insulated, 20' Non-operating reefer, 20' Open top, 20' Reefer, 20' Reefer high cube, 20' Tank tainer, 20' Vent container, 40' Flat bed, 40' Flat collapsible, 40' Flatrack, 40' General purpose, 40' High cube, 40' Insulated, 40' Non-operating reefer, 40' Open top, 40' Reefer, 40' Reefer high cube, 40' Tank tainer, 40' Vent container, 45' High cube, Bag, Bal uncompressed, Bale, Bale compressed, Basket, Bottle, Box, Break bulk, Bulk bag, Bulk, solid, grains, Bundle, Carton, Case, Case plywood, Coil, Container, Cradle, Crate, Cylender, Drum, Envelope, Keg, Octabin, Package, Pail, Pallet, Pallet, paper, Pallet, plastic, Pallet, plywood, Piece, Reel, Roll, Sack, Set, Sheet, Skid, Spool, Tube, Unit, Wooden case, Wooden crate

The following values are allowed for <packagecode>:

20FB, 20FC, 20FL, 20GP, 20HC, 20IS, 20NOR, 20OT, 20RF, 20RH, 20TK, 20VT, 40FB, 40FC, 40FL, 40GP, 40HC, 40IS, 40NOR, 40OT, 40RF, 40RH, 40TK, 40VT, 45HC, BAG, BLU, BAL, BLC, BSK, BOT, BOX, BBK, BBG, VR, BND, CTN, CAS, CAP, COI, CNT, CRD, CRT, CYL, DRM, ENV, KEG, OCT, PKG, PAI, PLT, PAP, PPT, PLP, PCE, REL, RLL, SA, SET, SHT, SKD, SPL, TUB, UNT, WCA, WCR

Other charges

Each <othercharges> element contains a <type> element and a <value> element.

^{<othercharges>
  <type>ADMIN</type>
  <value>1000</value>
</othercharges>}

The <type> element can have any of these values:

The <value> element is in the same currency as specified in <goodscurrency> (see Transport service).

File

There may be up to 8 <file> elements, each holds these required elements:

^{<type>image/png</type> <name>MyPhoto.png</name> <data>JVBERi0xLjQK.....RU9GCg==</data>}

<type> holds the mime type of the file; the following are allowed: appliation/pdf, image/jpeg, image/png.

<data> holds the file content, in base64. Files larger than 2 MBytes are ignored.

<name> holds the file name, this may not include '/' or '\' or '..' .

The first PDF that is included will be considered an invoice.

Dangerous goods