Repository navigation
Consignments
| Endpoint | /consignments.xml |
| Formats | XML |
| Authentication required? | Yes |
| Sender ID required? | Yes |
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.
Creating a consignment
cURL
curl -g -XPOST -d@consignment.xml -H'Content-Type: application/xml' -H'X-Cargonizer-Key: 12345' -H'X-Cargonizer-Sender: 678' 'https://api.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://api.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();
<!--Always begin with a <consignments> element. It is required.-->
<consignments>
<consignment transport_agreement="1433" print="false" estimate="false">
<!--
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.
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.
estimate: (Deprecated) Must be set to "false".
-->
<booking_request>false</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>false</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.
-->
<email-notification-to-consignee>false</email-notification-to-consignee>
<!--
Optional. By setting this value to “true”, Cargonizer will send the track&trace link
to the consignee by e-mail when the consignment is transferred to the carrier.
Default value is “false”, meaning that no e-mail is sent.
-->
<product>mypack</product>
<!--
Required. An identifier that specifies the transport product you want to use.
transport_agreements resource will give you a list to choose from.
For more details, see this list of valid identifiers
-->
<values>
<!--
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.
-->
<value name="provider" value="API Company AS"/>
<value name="provider-email" value="api@apicompany.no"/>
</values>
<parts>
<!--
Every party on the consignment comes under this element.
All elements are identical for each party unless otherwise stated. See below.
Possible parties are:
<consignee> Required. The party that will receive the packages.
<service_partner> Optional. Required if using Postnord ServicePoint/Parcel Locker product.
The pick-up point that this consignment will be delivered to.
Consignee will pick up the parcels at this address.
Use the service_partners.xml to get a correct servicepartner.
<return_addres> Optional. 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 consignor part as return address,
but not always. Adding a specific return address will then
make sure all returns are returned correctly.
<freight_payer_address> Optional. Only to be used when an external party pays freight.
<pickup_address> Optional. The party where the packages are to be collected by the carrier.
This part is not available for all carriers.
-->
<consignee freight_payer="false">
<!--
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. -->
</number>
<name>
<!-- Required. Name of the Consignee. -->
</name>
<address1>
<!-- Optional. Street address. -->
</address1>
<address2>
<!-- Optional. Additional address information. -->
</address2>
<postcode>
<!-- Required -->
</postcode>
<city>
<!-- Required -->
</city>
<country>
<!-- Required. Only ISO 3166-1 (2-alpha) is supported. -->
</country>
<email>
<!-- Optional. The email address. -->
</email>
<mobile>
<!-- Optional. The mobile phone number. -->
</mobile>
<contact-person>
<!-- Optional. Contact person. Address attention. -->
</contact-person>
<customer-number>
<!-- Optional. The agreement number between this part and its carrier.
Only required when this part is freightpayer.
-->
</customer-number>
</consignee>
<service_partner>
<number>
<!-- Required. Number used to identify the partner. -->
</number>
<customer-number>
<!-- Required when shipping abroad with a Bring product
that is eglibe for pickup point/service point.
Example value: c===0010
-->
</customer-number>
<name>
<!-- Required. Name of the Partner. -->
</name>
<address1>
<!-- Required. Partners Street Address. -->
</address1>
<postcode>
<!-- Required. Partners Postal Code. -->
</postcode>
<city>
<!-- Required. Partners Name of City/Place name. -->
</city>
<country>
<!-- Required. Only ISO 3166-1 (2-alpha) is supported. -->
</country>
</service_partner>
<freight_payer_address>
<customer-number>
<!-- Required. The cusomer number known to the carrier. -->
</customer-number>
<!-- rest of elements identical to other parties -->
</freight_payer_address>
</parts>
<items>
<!--
Required. Each parcel comes under this node.
-->
<item type="package" amount="1" weight="1" volume="15" description="Varer">
<!--
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).
-->
<dangerous_goods amount="2" gross_weight="2" labels="3.1" net_weight="1"
description="WETTED with not less than 40% water, or mixture of alcohol and water, by mass"
name="MANNITOL HEXANITRATE (NITROMANNITE)"
packing_group="2" points="50" tunnel_code="(B/C)"
type="Plastkanne" un_number="3421"/>
<!-- Only to be used if item contains dangerous goods (ADR)
name: Required. Also referred to as technical name.
type: Optional. Description of the packing
amount: Optional. Number of GDS items.
description: Optional. Additional ADR information/n.o.s etc.
un_number: Required. International UN number
tunnel_code: Required. Tunnel code
labels: Required. Also referred to as hazard class
packing_group: Optional. Valid values: 1, 2, 3 or in Roman numerals (I, II, III)
gross_weight: Optional. Gross weight of ADR items
net_weight: Required. Net weight of ADR items
points: Optional. Points
-->
</item>
</items>
<!-- NVIT
https://mailchi.mp/d0de974335ed/bytt-til-fraktlsning-fra-logistra-og-spar-kostnader-14196304
https://mailchi.mp/aaf89673bc50/bytt-til-fraktlsning-fra-logistra-og-spar-kostnader-14196206
A <consignment> may contain several <nvit> elements, each element describing
a particular type of item.
quantity: Required; integer. Quantity of customs articles.
number: Required; string. HS customs number. 6-10 digits.
description: Required; string. Description of item(s).
gross-weight: Required; float.
net-weight: Optional; float.
origin-country: Optional; string. ISO 3166-1 alpha-2 country code.
currency: Optional; string. ISO 4217 3-letter currency code.
amount: Optional; float. Amount of `currency`.
-->
<nvit
quantity="5"
number="123456"
description="5 hand-rolled Macanudo cigars"
gross-weight="0.5"
net-weight="0.5"
origin-country="CU"
currency="CUP"
amount="1200.00"
/>
<services>
<!-- Optional. Additional transport services must be specified here. Not all transport products supports services. -->
<service id="postnord_notification_email" />
<service id="postnord_notification_sms" />
<!--
id: Required. An ID that identifies the service. Use transport_agreements resource to see id of possible services.
-->
</services>
<references>
<consignor><!-- Senders ref / typical order number --></consignor>
<consignee><!-- Receivers ref / Consignee reference --></consignee>
</references>
<messages>
<carrier><!-- Optional. Message to carrier. --></carrier>
<consignee><!-- Optional. Message to consignee. --></consignee>
</messages>
</consignment>
</consignments>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="post@logistra.no" />
<value name="orderno" value="123" />
<value name="deliveryno" value="8765" />
</values>Some shipping products require that Terms of Delivery (TOD) must be specified. This information consists of 4 attributes attached to a tod element inside the consignment element.
<consignment>
...
<tod code="EXW" country="SE" postcode="100 05" city="Stockholm"/>
...
</consignment>| code | descripton |
|---|---|
| EXW | Ex Works |
| FCA | Free Carrier seller's premises |
| CPT | Carriage Paid To buyer's premises |
| CIP | Carriage and Insurance Paid to buyer's premises |
| DAT | Delivered At Terminal |
| DAP | Delivered At Place |
| DDP | Delivered buyer's premises Duty Paid |
| FAS | Free alongside ship |
| FOB | Free on board |
| CFR | Cost and freight |
| CIF | Cost insurance and freight |
Here is an example of a very minimalistic XML
<consignments>
<consignment transport_agreement="1" print="false">
<values>
<value name="provider" value="Logistra AS" />
<value name="provider-email" value="post@logistra.no" />
</values>
<product>tg_stykkgods</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.
consignments>
<consignment transport_agreement="1" print="false">
<product>tg_stykkgods</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"/>
</items>
</consignment>
</consignments>Here is a more completed XML variant
<consignments>
<consignment transport_agreement="1" estimate="true" print="false">
<values>
<value name="provider" value="Logistra AS" />
<value name="provider-email" value="post@logistra.no" />
<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>
<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 groupage consignment for Postnord
<consignments>
<consignment transport_agreement="1" print="false">
<values>
<value name="provider" value="Logistra AS" />
<value name="provider-email" value="post@logistra.no" />
<value name="orderno" value="123" />
</values>
<transfer>true</transfer>
<product>tg_stykkgods</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" print="false">
<values>
<value name="provider" value="Logistra AS" />
<value name="provider-email" value="post@logistra.no" />
<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>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 show and describe the elements that we think is most useful. The XML Response will return elements that may not have any meaning to your implementation.
<consignments>
<consignment>
<number-with-checksum>4017071219003212178</number-with-checksum>
<!-- Consignment number. Unique number can be used as parameter for
Track & Trace among other. Generated by Cargonizer.
-->
<bundles>
<pieces>
<number-with-checksum>037880053855047</number-with-checksum>
<!-- Parcel identificator. SSCC number. Unique. Generated by Cargonizer. -->
</pieces>
<pieces>
<number-with-checksum>037880053855054</number-with-checksum>
</pieces>
</bundles>
<values>
<!-- The returned element as you specified it in the request XML. See description above. -->
<value name="order" value="123"/>
<value name="humbaba" value="enkidu"/>
</values>
<consignment-pdf>https://cargonizer.no/consignments/19.pdf</consignment-pdf>
<!-- URL for address and barocde labels -->
<waybill-pdf>https://cargonizer.logistra.no/consignments/19.pdf?type=waybill</waybill-pdf>
<!-- URL for waybill. -->
<tracking-url>https://my.postnord.no/tracking/70727320392974462</tracking-url>
<!-- URL to be used to Track & Trace the consignment -->
<cost-estimate>
<!-- Freight costs comes under this element -->
<net>71</net>
<!-- Net freight costs. Based on your transport_agreement -->
<gross>53</gross>
<!-- Gross freight costs. -->
</cost-estimate>
</consignment>
</consignments>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://api.cargonizer.logistra.no/consignments/26.pdf