Back

  1. Paazl
  2. I'm a developer
  3. Generic Carrier Interface

About the registration file

Avatar
Jaime Wijdh
2021-07-22 14:08:05 UTC
Follow

This article provides the technical details of the XML file that Paazl uses to send order information to a carrier. About the Generic Carrier interface provides the context for the use of this file.

Paazl sends a registration file for each confirmed webshop order when the associated shipment labels are generated via the web app or via a SOAP or REST API call.

File name format

The name of a registration file has the following format:

<generic carrier name>_<client number>_<date_time>.xml

Example: TRUNKRS_20181010001_20190713_151036.xml

Barcode format

The barcode of a shipping label will contain the number of your contract with the webshop concerned followed by a six-digit number (from 000000 to 999999).

Element specifications

Element Type Required? Description
registration Complex Required

Contains details of a webshop order
orders Complex Required

Contains information on a webshop's orders
order Complex Required

A specific order's details
reference String Required

A webshop's reference for an order
serviceCode String Required

A webshop's unique code for one of its stores
accountNumber String Required

The number of a contract that a webshop has with a carrier.

The webshop concerned supplies this number to Paazl.
preferredDeliveryDate Date Required

The date your customers selected at the checkout.
cod Complex Optional Contains information on the Cash On Delivery amount.
currency String Optional

The ISO 4217 code of the currency concerned. The default value is EUR.
value Decimal Optional

The amount that has to be paid on receipt of goods.
insurance Complex Optional

Contains information on the insured amount.
currency String Optional

The ISO 4217 code of the currency concerned. The default value is EUR.
value Integer Optional

The monetary value of an order.
shipper Complex Required

Contains details of the party that shipped an order.
companyName String Optional

The name of the company that is shipping an order
name String Required

The name of the party that is shipping the order
nameOther String Optional

Use this for any additional name information.
street String Required

The name of the street in which the shipper is located
streetNumber Integer Required

The house number of the shipper's address.
streetNumberSuffix String Optional

The house number extension (such as the "-A” in "12-A”) of the address from which an order is shipped
postalCode String Required

The postal code of the address from which an order is shipped.
town String Required

The city or town of the shipper's address.
country String Required

The ISO 3166-2 code for the country of the shipper's address.
return Complex Required

Contains details of the party to which an order is returned.
companyName String Required

The company name of the party to which an order is being returned.
name String Optional DEPRECATED
nameOther String Optional

DEPRECATED
street String Required

The name of the street to which goods are being returned.
streetNumber Integer Required

The house number of the address to which goods are being returned.
streetNumberSuffix String Optional

The house number extension (such as the "-A” in "12-A”) of the address to which an order is returned.
postalCode String Required

The postal code of the address to which an order is returned.
town String Required

The city or town of the address to which goods are being returned.
country String Required

The ISO 3166-2 code for the country of the address to which an order is being returned.
emailAddress String Optional

The email address of the party to which goods are being returned
phoneNumber String Optional

The phone number of the party to which goods are being returned
consignee Complex Required

Contains details of a party to which an order is shipped.
companyName String Optional

The name of the company to which an order is shipped
name String Required

The name of the party to which an order is being shipped.
nameOther String Optional

Use this for any additional name information.
street String Required

The name of the street to which an order is being shipped.
streetNumber Integer Required

The house number of the address to which an order is being shipped.
streetNumberSuffix String Optional

The house number extension (such as the "-A” in "12-A”) of the address to which an order is shipped.
postalCode String Required

The postal code of the address to which an order is shipped.
town String Required

The city or town of the address to which an order is being shipped.
country String Required

The ISO 3166-2 code for the country of the address to which an order is being shipped.
emailAddress String Optional

The email address of the party to which an order is being shipped
phoneNumber String Optional

The phone number of the party to which an order is being shipped
notifications Complex Optional

Contains values on the notification types and their email addresses or phone numbers.
notification Complex Optional

Contains values on the notification types and their email addresses or phone numbers.
notificationType String Optional

The medium by which delivery status information should be sent.

It has one of two possible values:

  • CONSIGNEE_EMAIL
  • CONSIGNEE_PHONE
notificationValue String Optional

A shipment's delivery status,
products Complex Optional

Contains information on the products making up an order
product Complex Optional

Contains information on one of the products making up an order
quantity Integer Required

The number of items of a particular product type in a shipment.
length Integer Optional

The length in whole centimeters (cm) of a product.
width Integer Optional

The width in whole centimeters (cm) of a product.
height Integer Optional

The height in whole centimeters (cm) of a product.
volume Double Optional

The volume of a product in cubic meters (m3), including packaging.
weight Double Required

The weight in kilograms (kg) of a product.
description String Optional

This contains a description needed for Customs purposes.
countryOfManufacture String Optional

The ISO 3166-2 code for the country in which the goods being shipped were manufactured.
unitPrice nonNegativeDecimal Optional

The price of a product.
unitPriceCurrency currencyCode Optional

The ISO 4217 code of the currency concerned. The default value is EUR.
hsTariffCode String Optional

The HS code for the commodity category of the product concerned.
direction directionType Optional

Concerns swap orders where some products are to be picked up at a pickup location with other delivered to the consignee's address.

Can have one of two values:

  • DELIVERY
  • PICKUP
shipments Complex Required

Contains barcodes belonging to the various shipments that make up an order
shipment Complex Required

Contains the barcodes belonging to one of the shipments that make up an order
packages Complex Required

Contains the barcodes of the various packages contained in a shipment.
package Complex Required

Contains the barcode of one of the products contained in a shipment
barcode String Required

The label's barcode generated by Paazl
additionalInstruction String Optional

If required by the carrier, this instruction will be printed on the address label.
version String Required

The currently used version of the registration file.

XSD

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema targetNamespace="http://www.paazl.com/schemas/registration" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:registration="http://www.paazl.com/schemas/registration">

<xs:element name="registration">
  <xs:complexType>
    <xs:sequence>
      <xs:element name="orders" type="registration:OrdersType" />
    </xs:sequence>
    <xs:attribute name="version" type="xs:string" use="required" />
  </xs:complexType>
</xs:element>
 
<xs:complexType name="OrdersType">
  <xs:sequence>
    <xs:element name="order" type="registration:OrderType" maxOccurs="unbounded" />
  </xs:sequence>
</xs:complexType>
    
<xs:complexType name="OrderType">
  <xs:sequence> 
    <xs:element name="reference" type="xs:string" />
    <xs:element name="serviceCode" type="xs:string" />
    <xs:element name="accountNumber" type="xs:string" />
    <xs:element name="preferredDeliveryDate" type="xs:date" />   
    <xs:element name="cod" type="registration:CodType" minOccurs="0" />
    <xs:element name="insurance" type="registration:InsuranceType" minOccurs="0" />
    <xs:element name="shipper" type="registration:ContactAndAddressType" />
    <xs:element name="return" type="registration:ContactAndAddressType" />
    <xs:element name="consignee" type="registration:ContactAndAddressType" />
    <xs:element name="notifications" type="registration:NotificationsType" />
    <xs:element name="products" type="registration:ProductsType" minOccurs="0" />
    <xs:element name="shipments" type="registration:ShipmentsType" />
    <xs:element name="additionalInstruction" type="xs:string" minOccurs="0" />
  </xs:sequence>
</xs:complexType>

<xs:complexType name="CodType">
  <xs:sequence>
    <xs:element name="currency" type="xs:string"/>
    <xs:element name="value" type="xs:decimal" />
  </xs:sequence>
</xs:complexType>
 
<xs:complexType name="InsuranceType">
  <xs:sequence>
    <xs:element name="currency" type="xs:string"/>
    <xs:element name="value" type="xs:int" />
  </xs:sequence>
</xs:complexType>

<xs:complexType name="ContactAndAddressType">
  <xs:sequence>
    <xs:element name="companyName" type="xs:string" minOccurs="0" />
    <xs:element name="name" type="xs:string" />
    <xs:element name="nameOther" type="xs:string" minOccurs="0" />
    <xs:element name="street" type="xs:string" />
    <xs:element name="streetNumber" type="xs:int" />
    <xs:element name="streetNumberSuffix" type="xs:string" minOccurs="0" />
    <xs:element name="postalCode" type="xs:string" />
    <xs:element name="town" type="xs:string" />
    <xs:element name="country" type="xs:string" />
    <xs:element name="emailAddress" type="xs:string" minOccurs="0" />
    <xs:element name="phoneNumber" type="xs:string" minOccurs="0" />
  </xs:sequence>
</xs:complexType>
 
<xs:complexType name="ProductsType">
  <xs:sequence>
    <xs:element name="product" type="registration:ProductType" minOccurs="0" maxOccurs="unbounded" />
  </xs:sequence>
</xs:complexType>
 
<xs:complexType name="ProductType">
  <xs:sequence>
    <xs:element name="quantity" type="xs:int" />
    <xs:element name="length" type="xs:int" minOccurs="0" />
    <xs:element name="width" type="xs:int" minOccurs="0" />
    <xs:element name="height" type="xs:int" minOccurs="0" />
    <xs:element name="volume" type="xs:double" minOccurs="0" />
    <xs:element name="weight" type="xs:double" />
    <xs:element name="description" type="xs:string" minOccurs="0" />
    <xs:element name="countryOfManufacture" minOccurs="0" type="xs:string" />
    <xs:element name="unitPrice" minOccurs="0" type="registration:nonNegativeDecimal" />
    <xs:element name="unitPriceCurrency" minOccurs="0" default="EUR" type="registration:currencyCode" />
    <xs:element name="hsTariffCode" minOccurs="0" type="xs:string" />
    <xs:element name="direction" minOccurs="0" type="registration:directionType" />
  </xs:sequence>
</xs:complexType>
 
<xs:complexType name="ShipmentsType">
  <xs:sequence>
     <xs:element name="shipment" type="registration:ShipmentType" maxOccurs="unbounded" />
  </xs:sequence>
</xs:complexType>
 
<xs:complexType name="ShipmentType">
  <xs:sequence>
    <xs:element name="packages" type="registration:PackagesType" />
  </xs:sequence>
</xs:complexType>
 
<xs:complexType name="PackagesType">
  <xs:sequence>
    <xs:element name="package" type="registration:PackageType" maxOccurs="unbounded" />
  </xs:sequence>
</xs:complexType>
 
<xs:complexType name="PackageType">
  <xs:sequence>
    <xs:element name="barcode" type="xs:string" />
  </xs:sequence>
</xs:complexType>
 
<xs:complexType name="NotificationsType">
  <xs:sequence>
    <xs:element name="notification" type="registration:NotificationType" maxOccurs="unbounded" />
  </xs:sequence>
</xs:complexType>
    
<xs:complexType name="NotificationType">
  <xs:sequence>
    <xs:element name="notificationType" type="registration:genericNotificationType" />
    <xs:element name="notificationValue" type="xs:string" />
  </xs:sequence>
</xs:complexType>
 
<xs:simpleType name="genericNotificationType">
  <xs:restriction base="xs:string">
    <xs:enumeration value="CONSIGNEE_EMAIL"/>
    <xs:enumeration value="CONSIGNEE_PHONE"/>
  </xs:restriction>
</xs:simpleType>
 
<xs:simpleType name="nonNegativeDecimal">
  <xs:restriction base="xs:decimal">
    <xs:minInclusive value="0"/>
  </xs:restriction>
</xs:simpleType>
 
<xs:simpleType name="currencyCode">
  <xs:restriction base="xs:string">
    <xs:length value="3"/>
    <xs:pattern value="[A-Z]{3}"/>
  </xs:restriction>
</xs:simpleType> 
 
<xs:simpleType name="directionType">
  <xs:restriction base="xs:string">
    <xs:enumeration value="pickup"/>
    <xs:enumeration value="delivery"/>
  </xs:restriction>
</xs:simpleType> 

</xs:schema>

Examples

COD

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<registration xmlns="http://www.paazl.com/schemas/registration" version="1.0">
  <orders>
    <order>
    <serviceCode>PROD5</serviceCode>
    <cod>
     <currency>EUR</currency>
     <value>50.00</value>
    </cod>
    <shipperAddress>
     <companyName>Paazl</companyName>
     <street>Kerkstraat</street>
     <streetNumber>310</streetNumber>
     <postalCode>1017HC</postalCode>
     <town>Amsterdam</town>
     <country>NL</country>
    </shipperAddress>
    <returnAddress>
     <companyName>Paazl</companyName>
     <street>Kerkstraat</street>
     <streetNumber>310</streetNumber>
     <postalCode>1017HC</postalCode>
     <town>Amsterdam</town>
     <country>NL</country>
    </returnAddress>
    <consignee>
     <companyName>A Company BV</companyName>
     <name>My Name</name>
     <nameOther>Extra name field</nameOther>
     <street>Damrak</street>
     <streetNumber>70</streetNumber>
     <streetNumberSuffix>1</streetNumberSuffix>
     <postalCode>1012LM</postalCode>
     <town>Amsterdam</town>
     <country>NL</country>
    </consignee>
    <shipments>
     <shipment>
      <packages>
       <package>
        <barcode>1234500000100</barcode>
       </package>
      </packages>
     </shipment>
    </shipments>
    <additionalInstruction>Please leave parcel at number 20</additionalInstruction>
   </order>
  </orders>
</registration>

Insurance

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<registration xmlns="http://www.paazl.com/schemas/registration" version="1.0">
 <orders>
   <order>
    <serviceCode>PROD5</serviceCode>
    <insurance>
     <currency>EUR</currency>
     <value>150.00</value>
    </insurance>
    <shipperAddress>
     <companyName>Paazl</companyName>
     <street>Kerkstraat</street>
     <streetNumber>310</streetNumber>
     <postalCode>1017HC</postalCode>
     <town>Amsterdam</town>
     <country>NL</country>
    </shipperAddress>
    <returnAddress>
     <companyName>Paazl</companyName>
     <street>Kerkstraat</street>
     <streetNumber>310</streetNumber>
     <postalCode>1017HC</postalCode>
     <town>Amsterdam</town>
     <country>NL</country>
    </returnAddress>
    <consignee>
     <companyName>A Company BV</companyName>
     <name>My Name</name>
     <nameOther>Extra name field</nameOther>
     <street>Damrak</street>
     <streetNumber>70</streetNumber>
     <streetNumberSuffix>1</streetNumberSuffix>
     <postalCode>1012LM</postalCode>
     <town>Amsterdam</town>
     <country>NL</country>
    </consignee>
   <shipments>
     <shipment>
      <packages>
       <package>
        <barcode>1234500000100</barcode>
       </package>
      </packages>
     </shipment>
    </shipments>
    <additionalInstruction>Please leave parcel at number 20</additionalInstruction>
   </order>
  </orders>
</registration>

Was this article helpful?