Consignments

The consignment is what most of the system revolves around. Most other resources are related to consignments in one way or the other. It represents one or more physical parcels that are to be transported, containing information about the parties involved (consignee, consignor), who's transporting it (the carrier), which of the carrier's products you're using and any additional services you want to attach to the consignment.

  • Requires authentication: Yes
  • Requires sender ID: Yes

Related resources

Usage

Creating a consignment
cURL
curl -g -XPOST Denne e-postadressen er beskyttet mot programmer som samler e-postadresser. Du må aktivere javaskript for å kunne se den. -H'Content-Type: application/xml' -H'X-Cargonizer-Key: 12345' -H'X-Cargonizer-Sender: 678' 'https://cargonizer.no/consignments.xml'
HTTP
POST /consignments.xml HTTP/1.1 Host: cargonizer.no Content-Type: application/xml X-Cargonizer-Key: 12345 X-Cargonizer-Sender: 678 <contents of file "consignment.xml">
Pseudocode
http = new HTTPRequest(); http.method = 'POST'; http.url = 'https://cargonizer.no/consignments.xml'; http.headers.add('Content-Type', 'application/xml'); http.headers.add('X-Cargonizer-Key', '12345'); http.headers.add('X-Cargonizer-Sender', '678'); http.body = new File('consignment.xml').read(); response = http.execute();

XML

The consignment is described using the following XML structure. Not all fields are required.

<consignments>   Required. Root node. Each individual consignment must be located under this node. Multiple consignments are not supportet yet.
<consignment> transport_agreement Required. Unique per consignor. You can use the transport_agreement resource to get a valid list of agreements or contact Logistra if this is out of your reach.
  estimate Optional. If set to “true” Cargonizer will try to calculate the freight costs.
  print Deprecated. It is recommended to implement and use our printing API and keep this set to "false". Using our printing API will give you a better control and it is imperative to use the printing api if the sender has more than one DirectPrint.
<transfer>   If "true": The consignment will be automaticaly transfered to the carrier. If "false": You will need to log in to cargonizer and transfer it from there.
<booking_request>   Optional. By setting this value to “true”, you will inform the carrier to do a physical pickup from your consignors address. Default value is “false”, meaning no pickup is initiated based on your consignment information you send to the carrier
<email_label_to_consignee>   Optional only when generating return shipments. By setting this value to “true”, you will send the return label as a pdf file to the conisignee by e-mail. Default value is “false”, meaning that no e-mail is sent.
<values> <value> To be used freely. You make up your own key-value pairs so you can refer to your consignment from your own data. The same elements will be passed back to you. Feel free to use it as you like, but please include a value "provider" tag identifying you as the provider of this xml. See examples and more info below.
<product>   Required. An identifier that specifies the transport product you want to use. This resource will give you a list to choose from. For more details, see this list of valid identifiers
<parts>   All parties or addresses must be under this node
<consignee>   Required. The party that will receive the packages
  freight_payer Optional. Value is “true” if consignee is to pay for the shipping costs. “false” is the default value. If set to “false” or not spesified, consignor or another part will be used as freight payer
  <number> Optional. The consignors own ID for this party
  <name> Required. Name of the Consignee.
  <address1> Optional. Street address
  <address2> Optional. Street address. To be used to complete address1 if necessary
  <postcode> Required
  <city> Optional. If not specified Cargonizer will try to look it up based on country and postcode. If you dont specify a city, an error will be generated if it cant find the city name based on country and postcode. This might occur.
  <country> Required. Only ISO 3166-1 (2-alpha) is supported.
  <email> Optional. The email address.
  <mobile> Optional. The mobile phone number.
  <phone> Optional. The landline phone number.
  <fax> Optional. The fax number.
  <contact-person> Optional. Contact person. Address attention.
  <customer-number> Optional. The agreement number between this part and its carrier. Only required when this part is freightpayer.
<freight_payer_address>   Optional. Only to be used when an external party pays freight.
  <agent-number> Optional. Only to be used for some Bring products (cargo)
  <customer_number> Required. The cusomer number known to the carrier.
  <name> Required. Name of the Payer.
  <address1> Optional. Street address
  <address2> Optional. Street address. To be used to complete address1 if necessary
  <postcode> Required
  <city> Optional. If not specified Cargonizer will try to look it up based on country and postcode. If you dont specify a city, an error will be generated if it cant find the city name based on country and postcode. This might occur.
  <country> Required. Only ISO 3166-1 (2-alpha) is supported.
  <email> Optional. The email address.
  <mobile> Optional. The mobile phone number.
  <phone> Optional. The landline phone number.
  <fax> Optional. The fax number.
  <contact-person> Optional. Contact person. Address attention.
 <service_partner>   Optional. Required if using Postnord MyPack Collect, Return Dropoff or Mypack Home Small product. The pick-up point that this consignment will be delivered to. Consignee will pick up the parcels at this address. Contact Postnord AS to get the XML containing all pick-up points, or use this resource
  <number> Required. Number used to identify the partner.
  <name> Required. Name of the pick-up point
  <address1> Optional. Street address of the pick-up point.
  <postcode>  Required.
  <city> Required.
  <country> Required. Only ISO 3166-1 (2-alpha) is supported.
<return_address>   A xml received without a return address will null the return-to data that is registered back-end. In most cases this carrier then will use the consignee part as return address, but not always. Adding a specific return address will then make sure all returns are returned correctly.
  <name> Optional. Name of the Consignor.
  <address1> Optional. Street address
  <address2> Optional. Additional address
  <postcode>  Optional. PostCode
  <city> Optional. If not specified Cargonizer will try to look it up based on country and postcode. If you dont specify a city, an error will be generated if it cant find the city name based on country and postcode. This might occur.
  <country> Optional. Only ISO 3166-1 (2-alpha) is supported.
 <items>   Required. Each parcel comes under this node
 <item>  type Required. Type of parcel. Available parcel types for each carrier and product are found in the response of transport-agreements.xml
   amount Required. Number of parcels. Cargonizer will generate this amount of labels
   weight Conditional. The total weight of the parcel(s). Must be specified for some transport products
   volume Conditional. The total volume of the parcel(s) in dm3. Must be specified for some transport products.
   length Optional. The total length of the parcel in cm. Not useful if the amount attribute is greater than 1
   height Optional. The total height of the parcel in cm. Not useful if the amount attribute is greater than 1.
   width Optional. The total width of the parcel in cm. Not useful if the amount attribute is greater than 1
  load-meter Optional. Load Metres of the parcel in metres.
   description Optional. A description of the content inside this parcel(s)
<services>   Optional. Additional transport services must be specified here. Not all transport products supports services
<service>  id Required. An ID that identifies the service. See this list of valid identifiers
<references>   Optional. Place all of your references inside this node.
   <consignor> Optional. Senders reference
   <consignee> Optional. Consignees reference.
<messages>   Optional. Place all of your messages/transport instructions here
  <carrier> Optional. Message to carrier.
  <consignee> Optional. Message to consignee.

Using the <values> element

The concept with this element is to let you specify freely chosen name – value pair that is guaranteed to be returned identically back in the response XML. By using this element you will establish a connection between the information you send in and the information that is returned back to you. Look at it as the link between the XML request and the XML response.

In order to identify the provider of the xml we also would like if you added your company information here.

Here is an example, where first the provider is presented and the next tag is named orderno, and 123 is the orderno. We have also added a delivery number with the value 8765.

<values>
  <value name="provider" value="Logistra AS" />
  <value name="provider-email" value="Denne e-postadressen er beskyttet mot programmer som samler e-postadresser. Du må aktivere javaskript for å kunne se den." />
  <value name="orderno" value="123" />
  <value name="deliveryno" value="8765" />
</values>

Examples

Here is an example of a very minimalistic XML

<consignments>
    <consignment transport_agreement="1">
     <values>
	 <value name="provider" value="Logistra AS" />
         <value name="provider-email" value="Denne e-postadressen er beskyttet mot programmer som samler e-postadresser. Du må aktivere javaskript for å kunne se den." />
     </values>
    <product>tg_dpd_innland</product>
    <parts>
        <consignee>
            <name>Juan Ponce de Leon</name>
            <postcode>1337</postcode>
            <city>Sandvika</city>
            <country>NO</country>
        </consignee>
    </parts>
    <items>
        <item type="package" amount="1" weight="2.54" volume="3" description="Something"/>
    </items>
    </consignment>
</consignments>

Here is an example of a absolute minimal XML. Note: Providing a city is recommended.

<consignments>
  <consignment transport_agreement="1">
    <product>tg_dpd_innland</product>
      <parts>
        <consignee>
          <name>Juan Ponce de Leon</name>
          <postcode>1337</postcode>
          <country>NO</country>
        </consignee>
      </parts>
    <items>
      <item type="package" amount="1" weight="2.54"/>
    </items>
  </consignment>
</consignments>

Here is a more completed XML variant

<consignments>
  <consignment transport_agreement="1" estimate="true">
    <values>
      <value name="provider" value="Logistra AS" />
      <value name="provider-email" value="Denne e-postadressen er beskyttet mot programmer som samler e-postadresser. Du må aktivere javaskript for å kunne se den." />
      <value name="order" value="123" />
      <value name="humbaba" value="enkidu" />
    </values>
    <transfer>true</transfer>
    <booking_request>true</booking_request>
    <product>tg_stykkgods</product>
    <parts>
      <consignee>
        <name>Juan Ponce de Leon</name>
        <postcode>1337</postcode>
        <address1>Street address</address1>
        <city>Sandvika</city>
        <country>NO</country>
        <address1>Street 5</address1>
        <mobile>98989898</mobile>
        <contact-person>Juan</contact-person>
      </consignee>
      <pickup_address id="1"/><!-- Lookup from DB -->
      <return_address>
        <name>Company Inc.</name>
        <address1>Street 10</address1>
        <postcode>1337</postcode><!-- Lookup -->
        <country>NO</country>
      </return_address>
    </parts>
    <items>
      <item type="package" amount="1" weight="2.54" volume="3" description="Something"/>
      <item type="package" amount="1" weight="22" volume="122" description="Something else"/>
    </items>
    <services>
      <service id="insurance">
        <currency>NOK</currency>
        <amount>500</amount>
      </service>
    </services>
    <references>
      <consignor>Consignors reference</consignor>
      <consignee>Consignees reference</consignee>
    </references>
    <messages>
      <carrier>Contact Fred before delivery</carrier>
      <consignee>Please contact me before unpacking</consignee>
    </messages>
  </consignment>
</consignments>

Here is a typical example of a DPD consignment for Postnord

<consignments>
  <consignment transport_agreement="1">
    <values>
	<value name="provider" value="Logistra AS" />
        <value name="provider-email" value="Denne e-postadressen er beskyttet mot programmer som samler e-postadresser. Du må aktivere javaskript for å kunne se den." />
	<value name="orderno" value="123" />
    </values>
    <transfer>true</transfer>
    <product>tg_dpd_innland</product>
    <parts>
      <consignee>
        <name>Juan Ponce de Leon</name>
        <postcode>1337</postcode>
        <city>Sandvika</city>
        <country>NO</country>
      </consignee>
    </parts>
    <items>
      <item type="package" amount="1" weight="2.54" volume="3" description="Something"/>
    </items>
    <references>
      <consignor>Consignor ref</consignor>
    </references>
  </consignment>
</consignments>

Typical example of a MyPack consignment for PostNord with the service SMS notification added

<consignments>
  <consignment transport_agreement="1">
    <values>
        <value name="provider" value="Logistra AS" />
        <value name="provider-email" value="Denne e-postadressen er beskyttet mot programmer som samler e-postadresser. Du må aktivere javaskript for å kunne se den." />
        <value name="orderno" value="123" />
    </values>
    <transfer>true</transfer>
    <product>mypack</product>
    <parts>
      <consignee>
        <name>Knut Hansen</name>
        <country>NO</country>
        <postcode>6310</postcode>
        <city>Veblungsnes</city>
      </consignee>
      <service_partner>
        <number>3042033</number>
        <name>ROMSDAL BLOMSTER OG GAVER</name>
        <address1>RAUMASENTERET ØRAN</address1>
        <country>NO</country>
        <postcode>6300</postcode>
        <city>Åndalsnes</city>
      </service_partner>
    </parts>
    <items>
      <item type="package" amount="1" weight="2.54" volume="3" description="Something"/>
    </items>
    <services>
      <service id="postnord_notification_sms"></service>
    </services>
    <references>
      <consignor>Consignor ref</consignor>
    </references>
  </consignment>
</consignments>

XML Response Descripton

The Response XML will always return complete information about a consignment. This means its up to you to decide what information to use. In this documentation we will only describe the elements that is implemented or activated in Cargonizer. The XML Response will return elements that may not have any meaning to your implementation. Elements that we find most useful in an implementation is highlighted.

<consignments type=”array”> Each consignment comes under this element
<consignment>    Consignment information comes under this tag
<consignee-reference>    Consignees reference text
<consignor-reference>    Senders reference text
<created-at type=”datetime”>    Date and time when this consignment is generated in Cargonizer
<freight-payer-key>    Informs you about wich party is paying for the transport 
<id> Cargonizers internal ID of the consignment
<product-id type=”integer”>    Cargonizers internal ID of the transport product
<transport-agreement-id type=”integer”>    Cargonizers internal ID of the agreement that is used
<number-with-checksum>    Consignment number. Unique number can be used as parameter for Track & Trace among other. Generated by Cargonizer.
<addresses type=”array”>    Name and address of each involved part comes under this element. All parties has identical information. Only ConsigneeAddress is used here for better readability
<address type=”ConsigneeAddress”>    Each of the parties is identified by type. The types are:
ConsigneeAddress
PickupAddress
ReturnAddress
ServicePartnerAddress
<address1>    Street address
<address2>    Additional address information
<city>    Name of city
<contact-person>    Name of contact person
<country>    Country code
<email>    E-mail address
<mobile>    Cell phone number
<name>    Name of the party
<phone>    Phone number
<postcode>    Postcode – Zip
<bundles type=”array”>    Each parcel comes under this element
<bundle>    Details of each parcel comes under this tag
<description>    Description of the content inside the parcel
<height type=”float”>    The heigt of the parcel in cm.
<length type=”float”>    The length of the parcel in cm.
<load-meter type=”float”>    Amount of loadmetres this parcel is occupying.
<longname>    Type of parcel in full format
<pallet-places type=”integer”>    Number of pallet places this parcel is occupying
<shortname>    Type of parcel in code / shortname format. May differ between carriers.
<volume type=”float”>    Volume of the parcel in dm3
<weight type=”float”>    Weight of the parcel in kg.
<width type=”float”>    Width of the parcel in cm.
<pieces type=”array”>    Each single parcel’s unique characteristics comes under this element
<piece>    Single parcel element
<number-with-checksum>    Parcel identificator. SSCC number. Unique. Generated by Cargonizer.
<values>    The returned element as you specified it in the request XML. See description above.
<value name value>     
<consignment-pdf>    URL for address and barocde labels.
<waybill-pdf>    URL for waybill.
<tracking-url>    URL to be used to Track & Trace the consignment
<cost-estimate    Freight costs comes under this element
<net>    Net freight costs. Based on your transport_agreement
<gross>    Gross freight costs.

XML Response with Example Values

<?xml version="1.0" encoding="UTF-8"?>
<consignments type="array">
  <consignment>
    <freight-payer-key>consignor</freight-payer-key>
    <id type="integer">19</id>
    ...
    <product-id type="integer">1</product-id>
    ...
    <transport-agreement-id type="integer">1</transport-agreement-id>
    <number-with-checksum>037880053855047</number-with-checksum>
    <addresses type="array">
      <address type="ConsigneeAddress">
        <address1 nil="true"></address1>
        <address2 nil="true"></address2>
        <city>Sandvika</city>
        <consignment-id type="integer">19</consignment-id>
        <contact-person nil="true"></contact-person>
        <country>NO</country>
        <email nil="true"></email>
        <fax nil="true"></fax>
        <freight-payer type="boolean" nil="true"></freight-payer>
        <number nil="true"></number>
        <phone nil="true"></phone>
        <postcode>1337</postcode>
      </address>
      <address type="ReturnAddress">
        ...
      </address>
    </addresses>
    <bundles type="array">
      <bundle>
        ...
        <description>Something</description>
        <height type="
float">0</height>
        <load-meter type="float">0</load-meter>
        <pallet-places type="integer" nil="true"></pallet-places>
        <volume type="
float">3</volume>
        <weight type="
float">2</weight>
        <width type="
float">0</width>
        <pieces type="array">
          <piece>
            ...
            <number-with-checksum nil="true"></number-with-checksum>
          </piece>
        </pieces>
    </bundles>
    <values>
      </bundle>
      <value name="order" value="123"/>
      <value name="humbaba" value="enkidu"/>
    </values>
    <consignment-pdf>https://cargonizer.no/consignments/19.pdf</consignment-pdf>
    <waybill-pdf>https://cargonizer.logistra.no/consignments/19.pdf?type=waybill</waybill-pdf>
    <tracking-url>https://www.tollpost.no/wwwappl/send_foresp.epl?p_ref_type=send_nr&p_ref=4017071219003212178</tracking-url>
    <cost-estimate>
       <net>71</net>
       <gross>53</gross>
     </cost-estimate>
  </consignment>
</consignments>

Using the Response Values

Some of the elements in the response XML contains an URL. Those URL’s is only accessible trough an API call. It can not be referenced directly. Here is how to download url values in the response XML:

curl -H'X-Cargonizer-Key:9d6116ba' -H'X-Cargonizer-Sender:6' -XGET https://cargonizer.logistra.no/consignments/26.pdf

Just replace the URL with the one you want from the response XML.

XML Response Error

This section discusses the XML response that may accompany a failed API request. When an API request fails, Cargonizer will return an XML response that provides more specific information about the error(s) that caused the failure.

Transport Rule Violation
Error messages from Cargonizer will have the following format when there is a violation of the rules for a valid Consignment:

 <consignments>     Each Consignment that fails comes under this tag
 <consignment>     Consignment that failed
 <errors>     All lines describing the error will come under this node
 <error>     Textline describing the error

Example

<?xml version="1.0" encoding="UTF-8"?>
<consignments>
  <consignment>
    <errors>
      <error>Mottaker er ugyldig</error>
      <error>Dette produktet tillater ikke at sendingen sendes utenlands</error>
      <error>Mottakers adresse: Postnr. er ugyldig for DPD-sending</error>
    </errors>
  </consignment>
</consignments>

General Error

Error messages from Cargonizer will have the following format when there is a general error:

 <error>     Text describing the error.

Example

<?xml version="1.0" encoding="UTF-8"?>
<error>RuntimeError: Called id for nil, which would mistakenly be 4 -- if you really....etc</error>

Shipping Calculation Error

Example

<cost-estimate-error>Need weight or volume</cost-estimate-error>

 

 

 

Developer: Cargonizer API Documentation © Logistra AS   Øran Vest, 6300 Åndalsnes   Denne e-postadressen er beskyttet mot programmer som samler e-postadresser. Du må aktivere javaskript for å kunne se den.logistra facebook icon logistra twitter icon

Vi bruker informasjonskapsler (cookies) for å forbedre bruksopplevelsen og for å kunne føre statistikk over våre besøkende.