Requirements

The basic requirements needed to fully implement an API integration are:

Palletways cannot provide the developers to configure your systems directly, but we do have a full IT support team and a dedicated integration manager to assist in the integration process.

We are available to answer any queries and assist in the testing process.

Contact details:

0845 1530 007

Create a Consignment

For each new delivery that is required, your application needs to:

  1. Create consignment data that is in the appropriate format for the Palletways system. The data can be in XML or JSON. 

    The consignment data has to be structured in a particular way (see the example consignment we have included).  Your application needs to create consignment data that uses the same structure as the example.

    For information on the various  tags, see Create Consignment Tags.

  2. Send the consignment data to the appropriate endpoint URL, including the necessary parameters as part of the URL.

When the Palletways system receives consignment data, it validates it and  provides a response. The response indicates whether the data is valid and whether it has been committed to the system as a new consignment. Your application needs to be able to process the various responses.

<?xml version="1.0" encoding="UTF-8"?>
<Manifest>
  <Date>2017-06-08</Date>
  <Time>15:40:00</Time>
  <Confirm>no</Confirm>
  <Depot>
    <Account>
      <Consignment>
        <Type>D</Type>
        <ImportID>123</ImportID>
        <Number>Con123</Number>
        <Reference>CustomerRef1</Reference>
        <Lifts>3</Lifts>
        <Weight>147</Weight>
        <Handball>true</Handball>
        <TailLift>false</TailLift>
        <BookInRequest>true</BookInRequest>
        <BookInInstructions>This is booking in information for Con123.</BookInInstructions>
        <ManifestNote>Special Instructions are placed here</ManifestNote>
        <CollectionDate>2017-02-01</CollectionDate>
        <DeliveryDate>2017-12-03</DeliveryDate>
        <DeliveryTime>23:59:59</DeliveryTime>
        <Service>
          <Type>Collection</Type>
          <Code>B</Code>
          <Surcharge>N</Surcharge>
        </Service>
        <Address>
          <Type>Delivery</Type>
          <ContactName>Nick James</ContactName>
          <Telephone>447777123457</Telephone>
          <Fax>+441543000000</Fax>
          <CompanyName>A Good Company Ltd</CompanyName>
          <Line>1 Long Road</Line>
          <Line>Large District</Line>
          <Town>Lichfield</Town>
          <County>Staffordshire</County>
          <PostCode>WS13 8NE</PostCode>
          <Country>GB</Country>
        </Address>
        <Return>
          <Type>EU</Type>
          <Amount>5</Amount>
        </Return>
        <Return>
          <Type>EG</Type>
          <Amount>1</Amount>
        </Return>
        <Pallet>FY8491753</Pallet>
        <BillUnit>
          <Type>FP</Type>
          <Amount>3</Amount>
        </BillUnit>
        <BillUnit>
          <Type>HP</Type>
          <Amount>2</Amount>
        </BillUnit>
        <BillUnit>
          <Type>QP</Type>
          <Amount>1</Amount>
        </BillUnit>
        <ClientUnit>
          <Type>TMQP</Type>
          <Amount>6</Amount>
        </ClientUnit>
        <ClientUnit>
          <Type>TQP</Type>
          <Amount>3</Amount>
        </ClientUnit>
        <ClientUnit>
          <Type>TFP</Type>
          <Amount>7</Amount>
        </ClientUnit>
        <ClientUnit>
          <Type>FP</Type>
          <Amount>7</Amount>
        </ClientUnit>
        <NotificationSet>
          <SysGroup>1</SysGroup>
          <SysGroup>3</SysGroup>
          <SMSNumber>+447000000000</SMSNumber>
          <Email>nick_james@palletways.com</Email>
          <Email>vince_sutton@palletways.com</Email>
          <Email>richard_miller@palletways.com</Email>
        </NotificationSet>
        <CashPayment>
          <Amount>123,45</Amount>
          <Method>BD</Method>
          <CollectFrom>Delivery</CollectFrom>
          <FreeText>Please collect some money</FreeText>
        </CashPayment>
        <Product>
          <LineNo>1</LineNo>
          <Description>Screws</Description>
          <Quantity>6000</Quantity>
          <Code>HX120</Code>
        </Product>
        <Product>
          <LineNo>2</LineNo>
          <Description>Nails</Description>
          <Quantity>5000</Quantity>
          <Code>Nail1</Code>
          <Batch>Bat.001</Batch>
        </Product>
        <Product>
          <LineNo>3</LineNo>
          <Description>Sand bags</Description>
          <Quantity>16</Quantity>
          <Code>SndBag</Code>
        </Product>
      </Consignment>
    </Account>
  </Depot>
</Manifest>
{
    "Manifest": {
        "Date": "2017-06-08",
        "Time": "15:40:00",
        "Confirm": "no",
        "Depot": {
            "Account": [
                {
                    "Consignment": [
                        {
                            "Type": "D",
                            "ImportID": "123",
                            "Number": "Con123",
                            "Reference": "CustomerRef1",
                            "Lifts": "3",
                            "Weight": "147",
                            "Handball": "true",
                            "TailLift": "false",
                            "BookInRequest": "true",
                            "BookInInstructions": "This is booking in information for Con123.",
                            "ManifestNote": "Special Instructions are placed here",
                            "CollectionDate": "2017-02-01",
                            "DeliveryDate": "2017-12-03",
                            "DeliveryTime": "23:59:59",
                            "Service": {
                                "Type": "Collection",
                                "Code": "B",
                                "Surcharge": "N"
                            },
                            "Address": [
                                {
                                    "Type": "Delivery",
                                    "ContactName": "Nick James",
                                    "Telephone": "447777123457",
                                    "Fax": "+441543000000",
                                    "CompanyName": "A Good Company Ltd",
                                    "Line": [
                                        "1 Long Road",
                                        "Large District"
                                    ],
                                    "Town": "Lichfield",
                                    "County": "Staffordshire",
                                    "PostCode": "WS13 8NE",
                                    "Country": "GB"
                                }
                            ],
                            "Return": [
                                {
                                    "Type": "EU",
                                    "Amount": "5"
                                },
                                {
                                    "Type": "EG",
                                    "Amount": "1"
                                }
                            ],
                            "Pallet": "FY8491753",
                            "BillUnit": [
                                {
                                    "Type": "FP",
                                    "Amount": "3"
                                },
                                {
                                    "Type": "HP",
                                    "Amount": "2"
                                },
                                {
                                    "Type": "QP",
                                    "Amount": "1"
                                }
                            ],
                            "ClientUnit": [
                                {
                                    "Type": "FP",
                                    "Amount": "6"
                                },
                                {
                                    "Type": "TQP",
                                    "Amount": "3"
                                },
                                {
                                    "Type": "TFP",
                                    "Amount": "7"
                                },
                                {
                                    "Type": "FP",
                                    "Amount": "7"
                                }
                            ],
                            "NotificationSet": {
                                "SysGroup": [
                                    "1",
                                    "3"
                                ],
                                "SMSNumber": "+447000000000",
                                "Email": [
                                    "nick_james@palletways.com",
                                    "vince_sutton@palletways.com",
                                    "richard_miller@palletways.com"
                                ]
                            },
                            "CashPayment": {
                                "Amount": "123,45",
                                "Method": "BD",
                                "CollectFrom": "Delivery",
                                "FreeText": "Please collect some money"
                            },
                            "Product": [
                                {
                                    "LineNo": "1",
                                    "Description": "Screws",
                                    "Quantity": "6000",
                                    "Code": "HX120"
                                },
                                {
                                    "LineNo": "2",
                                    "Description": "Nails",
                                    "Quantity": "5000",
                                    "Code": "Nail1",
                                    "Batch": "Bat.001"
                                },
                                {
                                    "LineNo": "3",
                                    "Description": "Sand bags",
                                    "Quantity": "16",
                                    "Code": "SndBag"
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    }
}

Send a Consignment to the Endpoint URL

To create a new consignment in the Palletways system, your application needs to send consignment data to the following URL:

https://api.palletways.com/createconsignment

It also needs to append the URL with the create consignment parameters. These parameters can be used with GET and POST methods.

Caution

If your application sends data with the commit parameter set to "true", the Palletways system will store the data as a 'live' instance (as long as it is valid). Once the data is 'live', it cannot be changed, and if it has been created by mistake, it will need to be deleted at the depot. For this reason, we recommend that you set the commit parameter to "false" when testing your application, and only set commit to "true" when you know that the data is complete and valid. When commit is "false", the Palletways system will validate the data and provide a response, but it will not store the data as a 'live' record in the system.

Responses to Consignment Data

When you send consignment data to the Palletways system, it provides a response to indicate whether the data is valid and has been stored.

The possible responses vary, depending on whether the supplied data is valid and whether you included a commit parameter with a "true" value:

  • If your application provides valid data,  as valid XML or JSON, and sets the commit parameter to "false", the Palletways system responds with Successful (No data has been imported)

  • If your application provides valid data, as valid XML or JSON, and sets the commit parameter to "true", the Palletways system responds with  Successful (Consignment Type).

  • If your application provides invalid data, the Palletways system responds with Error Invalid Data.

  • If your application provides data that has incorrect XML or JSON, the Palletways system responds with Error Invalid Format .

Consignment has Invalid Data

When the Palletways system receives your consignment data, it checks it to make sure it is valid. It then sends a response to show the result of its validation check.

If you receive an Error Validation response, it means that there is a problem with the syntax of your consignment data. The XML or JSON may still be valid, but the consignment tags are in the wrong order or have invalid values. The error validation response provides details about which tags have incorrect values. You will need to correct these problems and resend the consignment data to the Palletways system.

The Palletways system will not accept invalid data.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Status>
    <Code>ERROR_VALIDATION</Code>
    <Description>Validation errors occurred. No data has been imported.</Description>
  </Status>
  <ValidationErrors>
    <Consignment>
      <Index>1</Index>
      <ImportID>CustID:123</ImportID>
      <Error>
        <Code>ERROR_CONSIGNMENT_TYPE_MANDATORY</Code>
        <Description>[Consignment] provided does not contain the required [Type] node.</Description>
      </Error>
      <Error>
        <Code>ERROR_CLIENTUNIT_TYPE_VALUE</Code>
        <Description>ClientUnit [Type] contain an invalid value. Value provided = [ZZZ].</Description>
      </Error>
      <Error>
        <Code>ERROR_BILLUNIT_AMOUNT_VALUE</Code>
        <Description>BillUnit [Amount] is not in the required [unsignedinteger] format. Value provided = [-3]</Description>
      </Error>
    </Consignment>
    <Consignment>
      <Index>2</Index>
      <ImportID>CustID:124</ImportID>
      <Error>
        <Code>ERROR_CONSIGNMENT_TYPE_MANDATORY</Code>
        <Description>[Consignment] provided does not contain the required [Type] node.</Description>
      </Error>
    </Consignment>
  </ValidationErrors>
</Response>
Example currently unavailable.

Consignment Data has Invalid Format

When the Palletways system receives your consignment data, it checks it to make sure it is valid. It then sends a response to show the result of its validation check.

If you receive an Error Format Invalid response, it means that the consignment data contains invalid XML or JSON code. You will need to correct the problem (see Send a Consignment to the Endpoint URL).

The Palletways system will not accept invalid XML or JSON data.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Status>
    <Code>ERROR_FORMAT_INVALID</Code>
    <Description>The supplied data could not be imported in the stated input format.</Description>
  </Status>
</Response>
Example currently unavailable.

Consignment Successful, Not Committed

If your application sends valid consignment data to the Palletways system, and the commit parameter is set to "false", Palletways provides a Successful (No data has been imported) validation response. Receiving this response means that the data is valid, but has not been stored in the Palletways system (and so is not a new, 'live' consignment). To turn the data into a new, 'live' consignment, your application would have to send the data with the commit parameter set to "true".

Note

If your consignment data is invalid, the Palletways system responds with an invalid format message or an invalid data message.

The Successful (No data has been imported) message is provided in XML or JSON, depending on what language you specified for the outputformat parameter (see Send a Consignment to the Endpoint URL).

Your application needs to be able to process the response from the Palletways system. We have included an example of a successful no data imported response.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Status>
    <Code>OK</Code>
    <Description>Successful</Description>
  </Status>
  <Detail>
    <Message>No data has been imported as it was not requested.</Message>
  </Detail>
</Response>
Example currently unavailable.

Consignment Successful and Committed

When the Palletways system receives a valid consignment that has the commit parameter set to "true", it responds with Successful (Consignment Type). Receiving this response means that your consignment data is valid and has been stored as a new,  'live' consignment in the Palletways system.

Note

If your consignment data is invalid, the Palletways system responds with an invalid format message or an invalid data message.

The Successful (Consignment Type) message is provided in XML or JSON, depending on what language you specified for the outputformat parameter (see Send a Consignment to the Endpoint URL).

Your application needs to be able to process the Successful (Consignment Type) response from the Palletways system. We have included an example to show the structure of the response data.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Status>
    <Code>OK</Code>
    <Description>Successful</Description>
  </Status>
  <Detail>
    <ImportDetail>
      <ImportID></ImportID>
      <ResponseID>3972953</ResponseID>
      <Information>Consignment type:Delivery. Requires confirmation before being sent to the depot system for processing.</Information>
    </ImportDetail>
  </Detail>
</Response>
Example currently unavailable.

Manifest

Manifest is a container for the returned data (not including status data).

Note

All job data needs to be within the manifest tags.

Child tag(s):

The data tags that contain values (are not containers) have to be nested inside Manifest tag. They are 'children' of the Manifest tag.

<Manifest>
 <!-- job data goes here -->
</Manifest>
"Manifest": {
Job data goes here,
}

Date

The date that the manifest was sent to the API.

Parent tag:

Manifest

Child tag(s):

None.

<Date>2017-06-08</Date>
"Date": "2017-06-08",

Time

Time the manifest was sent to the API.

Parent tag:

Manifest

Child tag(s):

None.

<Time>15:40:00</Time>
"Time": "15:40:00",

Confirm

Confirmation of data to Palletways. If confirmation is not specified, data will be held in the Portal and not committed to the depot.

Parent tag:

Manifest

Child tag(s):

None.

<Confirm>no</Confirm>
"Confirm": "no",

Depot

The depot tag is a container for an array of accounts.

Data type:

Alphanumeric. Free text field.

Parent tag:

Manifest

Child tag(s):

None.

<Depot>
<!-- Account details go here -->
</Depot>
"Depot": {
}

Account

The account tag is a 'container' for an array of consignments.

Data type:

Alphanumeric. Free text field.

Parent tag:

Manifest

Child tag(s):

None.

<Account>
<!-- Consignment details come here -->
</Account>
"Account": [
]

Consignment

Used to start / close a consignment. Individual consignment data is specified within each consignment tag.

Parent tag:

Manifest

Child tag(s):

Type (Consignment)

Import ID

Number

Reference

Lifts

Weight

Handball

TailLift

Insurance

BookInRequest

BookInInstructions

ManifestNote

CollectionDate

DeliveryDate

DeliveryTime

<Consignment>
    <!--  consignment data goes here -->
</Consignment>
"Consignment": [
],

Type (Consignment)

Type of consignment specified. Designates either a collection, delivery or third party consignment.

Data type:

Alphanumeric. Free text field.

Parent tag:

Consignment

Child tag(s):

None.

<Type>D</Type>
"Type": "D",

Import ID

ID specifIed by customer. Free text field, ID supplied by customer to reference successful consignment imports.

Data type:

Alphanumeric. Free text field.

Parent tag:

Consignment

Child tag(s):

None.

<ImportID>123</ImportID>
"ImportID": "123",

Number

An alphanumeric value used to identify a specific consignment or depot.

Data type:

Alphanumeric. Free text field.

Parent tag:

Consignment

Child tag(s):

None.

<Number>abc123456</Number>
"Number": "abc123456",

Reference

Customer reference. Free text field - customer reference number.

Data type:

Alphanumeric. Free text field.

Parent tag:

Consignment

Child tag(s):

None.

<Reference>abc123456</Reference>
"Reference": "abc123456",

Lifts

Number of lifts. Positive integer, total number of pallet lifts on the consignment.

Parent tag:

Consignment

Child tag(s):

None.

<Lifts>4</Lifts>
"Lifts": "4",

Weight

Weight of consignment. Positive integer, total weight in KG of the entire consignment.

Parent tag:

Consignment

Child tag(s):

None.

<Weight>1000</Weight>
"Weight": "1000",

Handball

Handball of goods required. Enable if the handball of goods is required.

Parent tag:

Consignment

Child tag(s):

None.

<Handball>true</Handball>
"Handball": "true",

TailLift

Tail lift service required. Enable if a tail lift service is required for delivery.

Parent tag:

Consignment

Child tag(s):

None.

<TailLift>true</TailLift>
"TailLift": "true",

Insurance

Insurance level required. Standard RSA insurance values (£ per 1000kg). Leave blank to select your account defaults.

Parent tag:

Consignment

Child tag(s):

None.

<Insurance>1300</Insurance>
"Insurance": "1300",

BookInRequest

Book in service required. Select if the consignment required booking in before delivery.

Parent tag:

Consignment

Child tag(s):

None.

<BookInRequest>true</BookInRequest>
"BookInRequest": "true",

BookInInstructions

Book in details. Free text field, required if the bookin request is true, provides book-in details for delivery member.

Data type:

Alphanumeric. Free text field.

Parent tag:

Consignment

Child tag(s):

None.

<BookInInstructions>This is booking in information for Con123</BookInInstructions>
"BookInInstructions": "This is booking in information for Con123true",

ManifestNote

Delivery instructions. Free text field, special instructions for the delivery member.

Data type:

Alphanumeric. Free text field.

Parent tag:

Consignment

Child tag(s):

None.

<ManifestNote>Special instructions for delivery go here.</ManifestNote>
"ManifestNote": "Special instructions for delivery go here.",

CollectionDate

The specified date of collection service.

Parent tag:

Consignment

Child tag(s):

None.

<CollectionDate>2017-06-08</CollectionDate>
"CollectionDate": "2017-06-08",

DeliveryDate

The specified date of delivery. Only applicable when a specified day can be selected.

Parent tag:

Consignment

Child tag(s):

None.

<DeliveryDate>2017-06-08</DeliveryDate>
"DeliveryDate": "2017-06-08",

DeliveryTime

Specified time of delivery. Only applicable if a timed service is selected.

Parent tag:

Consignment

Child tag(s):

None.

<DeliveryTime>13:45:00</DeliveryTime>
"DeliveryTime": "13:45:00",

Service

Used to start / close a service. The data for each service is specified in tags within each service tag.

Parent tag:

Manifest

Child tag(s):

ServiceType

Code (Service)Code (Service)

ServiceCode

<Service>
    <!--  service data goes here -->
</Service>
"Service": [
],

ServiceType

The type of service that can be provided. This can be collection, delivery , or thirdparty (for when another company provides the service).

Data type:

Alphanumeric. Free text field.

Parent tag:

Service

Child tag(s):

None.

<ServiceType>delivery</ServiceType>
"ServiceType": "delivery",

ServiceGroupCode

A code that represents the category of Palletways collection/delivery service, for example, PREMIUM. For more information on the codes, see Palletways Service Codes.

Data type:

Alphanumeric. Free text field.

Parent tag:

Service

Child tag(s):

None.

<ServiceGroupCode>B</ServiceGroupCode>
"ServiceGroupCode": "B",

ServiceCode

A code that represents the type of Palletways collection/delivery service, see Palletways Service Codes.

Data type:

Alphanumeric. Free text field.

Parent tag:

Service

Child tag(s):

None.

<ServiceCode>B</ServiceCode>
"ServiceCode": "B",

Address

Used to start / close a consignment address. The details of the address must be specified in the appropriate tags within the address tag.

Parent tag:

Manifest

Child tag(s):

Type (Address)

ContactName

Telephone

Fax

CompanyName

Line

Town

County

PostCode

Country

<Address>
    <!--  address data goes here -->
</Address>
"Address": [
],

Type (Address)

Type of service for the address. Specify the service type - collection, delivery , thirdparty.

Data type:

Alphanumeric. Free text field.

Parent tag:

Address

<Type>delivery</Type>
"Type": "delivery",

ContactName

Name of delivery contact.

Data type:

Alphanumeric. Free text field.

Parent tag:

Address

Child tag(s):

None.

<ContactName>John Smith</ContactName>
"ContactName": "John Smith",

Telephone

Specified telephone number.

Parent tag:

Address

Child tag(s):

None.

<Telephone>447777123457</Telephone>
"Telephone": "447777123457",

Fax

Specified fax line.

Parent tag:

Address

Child tag(s):

None.

<Fax>01234 567890</Fax>
"Fax": "01234 567890",

CompanyName

Specified company name.

Data type:

Alphanumeric. Free text field.

Parent tag:

Address

Child tag(s):

None.

<CompanyName>Palletways</CompanyName>
"CompanyName": "Palletways",

Line

Line in delivery address. Multiple lines can be supplied for an address (maximum 5).

Data type:

Alphanumeric. Free text field.

Parent tag:

Address

Child tag(s):

None.

<Line>1 Long Road</Line>
<Line>Large District</Line>
"Line": [
"1 Long Road",
"Large District"
],

Town

Specified town in address.

Data type:

Alphanumeric. Free text field.

Parent tag:

Address

<Town>Lichfield</Town>
"Town": "Lichfield",

County

Specified county in address.

Data type:

Alphanumeric. Free text field.

Parent tag:

Address

Child tag(s):

None.

<County>Staffordshire</County>
"County": "Staffordshire",

PostCode

Specified post code in address.

Data type:

Alphanumeric. Free text field.

Parent tag:

Address

Child tag(s):

None.

<PostCode>WS13 8NE</PostCode>
"PostCode": "WS13 8NE",

Country

Specified country in address. Enter in the ISO country code format. Country code required for service validation.

Data type:

Alphanumeric. Free text field.

Parent tag:

Address

Child tag(s):

None.

<Country>GB</Country>
"Country": "GB",

Pallet

A code for identifying a specific pallet.

Data type:

Alphanumeric. Free text field.

Parent tag:

Consignment

Child tag(s):

None.

<Pallet>FY8491753</Pallet>
 "Pallet": "FY8491753",

BillUnit

Use to start/close a bill unit (type of pallet). The data for each bill unit is specified in tags within each BillUnit tag. Each consignment can contain multiple billing units.

Parent tag:

Manifest

Child tag(s):

Type (BillUnit)

Amount

<BillUnit>
    <!--  bill unit data goes here -->
</BillUnit>
"BillUnit": [
],

Type (BillUnit)

Specify the billing units based on the pallet types provided in the consignment.

Data type:

Alphanumeric. Free text field.

Parent tag:

BillUnit

Child tag(s):

None.

<Type>FP</Type>
"Type": "FP",

Amount

Specify the number of billing units (pallets) in the consignment.

Parent tag:

BillUnit

Child tag(s):

None.

<Amount>3</Amount>
"Amount": "3",

NotificationSet

Used to start / close a notification set. The data for each notification set is specified in tags within each NotificationSet tag.

Parent tag:

Manifest

Child tag(s):

SysGroup

SMSNumber

Email

<NotificationSet>
    <!--  notification set data goes here -->
</NotificationSet>
"NotificationSet": [
],

SysGroup

Specified notification. Multiple Sysgroups can be requested per consignment, based on the customer notifications required.

Parent tag:

NotificationSet

Child tag(s):

None.

<SysGroup>3</SysGroup>
"SysGroup": "3",

SMSNumber

Number for SMS notifications.

Parent tag:

NotificationSet

Child tag(s):

None.

<SMSNumber>01234 567890</SMSNumber>
"SMSNumber": "01234 567890",

Email

Notification email. Multiple Email addresses can be specified.

Data type:

Alphanumeric. Free text field.

Parent tag:

NotificationSet

Child tag(s):

None.

<Email>user@palletways.com</Email>
"Email": [
“user1@palletways.com",
]

CashPayment

The CashPayment tag is a container element for data relating to cash payments for collections or deliveries.

Parent tag:

CashPayment

Child tag(s):

Amount

Method

CollectFrom

FreeText

<CashPayment>Cash payment data goes here</CashPayment>
 "CashPayment": {
  }

Amount (CashPayment)

The amount of cash that is to be paid.

Data type:

Numeric positive whole number.

Parent tag:

CashPayment

Child tag(s):

None.

<amount>325,65</amount>
 "amount": "365,25",

FreeText

Text content, for example, 'Please collect money on delivery'.

Data type:

Alphanumeric. Free text field.

Parent tag:

Is used with CashPayment and Note.

Child tag(s):

None.

<FreeText>Please collect money on delivery</FreeText>
 "FreeText": "Please collect money on delivery",

Product

Used to start / close a product entry. Product descriptions, quantities, line numbers, and codes have to be specified within a product tag.

Parent tag:

Manifest

Child tag(s):

LineNo

Description (Product)

Quantity

Code (Product)

<Product>
    <!--  product data goes here -->
</Product>
"Product": [
],

LineNo

Line the data is presented on. Start at line one and increase in increments of one to specify each line of data.

Parent tag:

Product

Child tag(s):

None.

<LineNo>2</LineNo>
"LineNo": "2",

Description (Product)

Product description.

Data type:

Alphanumeric. Free text field.

Parent tag:

Product

Child tag(s):

None.

<Description>Sand bags</Description>
"Description": "Sand bags",

Quantity

Quantity of product. Specify the number of product in the consignment.

Parent tag:

Product

Child tag(s):

None.

<Quantity>200</Quantity>
"Quantity": "200",

Code (Product)

Customer's product code.

Data type:

Alphanumeric. Free text field.

Parent tag:

Product

Child tag(s):

None.

<Code>Nail1</Code>
"Code": "Nail1",

Request a Consignment

You can get your application to request consignment data from the Palletways system. For example, many of our delivery partners request data from the Palletways system so that they can find out what they have to deliver. 

To request consignment data, your application needs to call this URL:

https://api.palletways.com/getconsignment

To specify which consignment notes are needed, the URL has to include various parameters.

When your application sends a consignment request, the Palletways system provides a response.

https://api.palletways.com/getconsignment/12345678912?apikey=0abC1dEfghIJklMNOPQ23RST4UVWX5Xzab6CD7eFGhi%8j&amp;outputformat=json

Responses to Consignment Requests

When your application makes a valid request for consignment data, the Palletways system responds with the consignment data, in the requested format. A valid request is a request that uses the correct endpoint URL, which includes a valid tracking number, valid API key, and output format.

Your application will need to be able to process the data that is returned. To illustrate the format of the data, we have included an example of returned consignment data (both XML and JSON).

If your request is invalid, the Palletways system provides an error message. Typically, invalid requests are caused by your application:

  • Calling an incorrect URL

  • Using incorrect syntax in the URL

  • Including an invalid tracking ID in the URL

  • Including an invalid API key in the URL

For information on how to create a valid request, see Endpoint URL for Consignment Request.Endpoint URL for Consignment Request

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Status>
    <Code>OK</Code>
    <Description>Successful</Description>
    <Count>4</Count>
  </Status>
  <Detail>
    <Data>
      <Delta>1493825934</Delta>
      <TrackingID>30018513734</TrackingID>
      <ConNo>100-03186</ConNo>
      <SysNote>2734</SysNote>
      <Barcode></Barcode>
      <NoteDate>2017-05-03</NoteDate>
      <NoteTime>17:37:16</NoteTime>
      <PodDate></PodDate>
      <PodTime></PodTime>
      <PodSignature></PodSignature>
      <BookInDate></BookInDate>
      <BookInTime></BookInTime>
      <BookInContact></BookInContact>
      <BookInReference></BookInReference>
      <NoteText>Palletways Automated Import&#13;File:734_X334_12310423_20170503_151244.csv&#13;Date:03/05/17&#13;Time:17:37:16&#13;&#13;PRE-ALERT REQUIRED&#13;</NoteText>
      <StatusCode>0</StatusCode>
      <NoteGroup>JIN</NoteGroup>
      <NoteType>IIN</NoteType>
    </Data>
    <Data>
      <Delta>1493854555</Delta>
      <TrackingID>30018513734</TrackingID>
      <ConNo>100-03186</ConNo>
      <SysNote>3996</SysNote>
      <Barcode>FY8177381</Barcode>
      <NoteDate>2017-05-04</NoteDate>
      <NoteTime>00:59:17</NoteTime>
      <PodDate></PodDate>
      <PodTime></PodTime>
      <PodSignature></PodSignature>
      <BookInDate></BookInDate>
      <BookInTime></BookInTime>
      <BookInContact></BookInContact>
      <BookInReference></BookInReference>
      <NoteText>Scan out of hub Homberg to depot 355 on DAPL8424</NoteText>
      <StatusCode>550</StatusCode>
      <NoteGroup>VL</NoteGroup>
      <NoteType>SCN</NoteType>
    </Data>
    <Data>
      <Delta>1493896555</Delta>
      <TrackingID>30018513734</TrackingID>
      <ConNo>100-03186</ConNo>
      <SysNote>4755</SysNote>
      <Barcode></Barcode>
      <NoteDate>2017-05-04</NoteDate>
      <NoteTime>13:08:24</NoteTime>
      <PodDate>2017-05-04</PodDate>
      <PodTime>10:40:00</PodTime>
      <PodSignature>Stempel</PodSignature>
      <BookInDate></BookInDate>
      <BookInTime></BookInTime>
      <BookInContact></BookInContact>
      <BookInReference></BookInReference>
      <NoteText></NoteText>
      <StatusCode>900</StatusCode>
      <NoteGroup>POD</NoteGroup>
      <NoteType>POD</NoteType>
    </Data>
    <Data>
      <Delta>1493897035</Delta>
      <TrackingID>30018513734</TrackingID>
      <ConNo>100-03186</ConNo>
      <SysNote>5755</SysNote>
      <Barcode>FY8177381</Barcode>
      <NoteDate>2017-05-04</NoteDate>
      <NoteTime>13:15:06</NoteTime>
      <PodDate></PodDate>
      <PodTime></PodTime>
      <PodSignature></PodSignature>
      <BookInDate></BookInDate>
      <BookInTime></BookInTime>
      <BookInContact></BookInContact>
      <BookInReference></BookInReference>
      <NoteText>de35530018513734P.1.tif</NoteText>
      <StatusCode>0</StatusCode>
      <NoteGroup>POD</NoteGroup>
      <NoteType>IMG</NoteType>
    </Data>
  </Detail>
</Response>
{
  "Status": {
  "Code": "OK",
  "Description": "Successful",
  "Count": 4
  },
  "Detail": {
  "Data": [
  {
  "Delta": "1493825934",
  "TrackingID": "30018513734",
  "ConNo": "100-03186",
  "SysNote": "2734",
  "Barcode": "",
  "NoteDate": "2017-05-03",
  "NoteTime": "17:37:16",
  "PodDate": null,
  "PodTime": null,
  "PodSignature": "",
  "BookInDate": null,
  "BookInTime": null,
  "BookInContact": "",
  "BookInReference": "",
  "NoteText": "Palletways Automated Import\rFile:734_X334_12310423_20170503_151244.csv\rDate:03\/05\/17\rTime:17:37:16\r\rPRE-ALERT REQUIRED\r",
  "StatusCode": "0",
  "NoteGroup": "JIN",
  "NoteType": "IIN"
  },
  {
  "Delta": "1493854555",
  "TrackingID": "30018513734",
  "ConNo": "100-03186",
  "SysNote": "3996",
  "Barcode": "FY8177381",
  "NoteDate": "2017-05-04",
  "NoteTime": "00:59:17",
  "PodDate": null,
  "PodTime": null,
  "PodSignature": "",
  "BookInDate": null,
  "BookInTime": null,
  "BookInContact": "",
  "BookInReference": "",
  "NoteText": "Scan out of hub Homberg to depot 355 on DAPL8424",
  "StatusCode": "550",
  "NoteGroup": "VL",
  "NoteType": "SCN"
  },
  {
  "Delta": "1493896555",
  "TrackingID": "30018513734",
  "ConNo": "100-03186",
  "SysNote": "4755",
  "Barcode": "",
  "NoteDate": "2017-05-04",
  "NoteTime": "13:08:24",
  "PodDate": "2017-05-04",
  "PodTime": "10:40:00",
  "PodSignature": "Stempel",
  "BookInDate": null,
  "BookInTime": null,
  "BookInContact": "",
  "BookInReference": "",
  "NoteText": "",
  "StatusCode": "900",
  "NoteGroup": "POD",
  "NoteType": "POD"
  },
  {
  "Delta": "1493897035",
  "TrackingID": "30018513734",
  "ConNo": "100-03186",
  "SysNote": "5755",
  "Barcode": "FY8177381",
  "NoteDate": "2017-05-04",
  "NoteTime": "13:15:06",
  "PodDate": null,
  "PodTime": null,
  "PodSignature": "",
  "BookInDate": null,
  "BookInTime": null,
  "BookInContact": "",
  "BookInReference": "",
  "NoteText": "de35530018513734P.1.tif",
  "StatusCode": "0",
  "NoteGroup": "POD",
  "NoteType": "IMG"
  }
  ]
  }
}

Request Consignment Tags

When the Palletways system responds to a valid request for consignment data, it returns XML or JSON that uses these tags:

Delta

The delta tag is a POSIX time stamp. It represents a start time for the data and is useful when you want to retrieve incremental updates. 

Data type:

Numeric positive whole number.

Parent tag:

Result

Child tag(s):

None.

<Delta>1320338091</Depot>
 "delta": "1320338091",

TrackingID

A number that is allocated to a consignment. It is used to track the location of the consignment in the Palletways collection/delivery network.

Data type:

Numeric positive whole number.

Parent tag:

Result

Child tag(s):

None.

<TrackingID>300005277501320338091</TrackingID>
 "TrackingID": "300005277501320338091",

Conno

The consignment number, which is used to identify the consignment. This is the number allocated to the consignment when it was created. 

Data type:

Alphanumeric. Free text field.

Parent tag:

Result

Child tag(s):

None.

<conno>EXPD1810-11320338091</conno>
 "conno": "EXPD1810-1320338091",

SysNote

Barcode

The barcode used to identify the consignment.

Data type:

Alphanumeric. Free text field.

Parent tag:

Result

Child tag(s):

None.

<barcode>1A0001898</barcode>
 "barcode": "1A0001898",

Note_Date

The date on which the note was created.

Data type:

Date

Parent tag:

Result

Child tag(s):

None.

<note_date>2018-08-15</note_date>
 "note_date": "2018-08-15",

Note_Time

The time at which the note was created.

Data type:

Time

Parent tag:

Result

Child tag(s):

None.

<note_time>20:45:01</note_time>
 "note_time": "20:45:01",

Pod_Date

The date on which the proof of delivery was created.

Data type:

Date

Parent tag:

Result

Child tag(s):

None.

<pod_date>2018-08-15</pod_date>
 "pod_date": "2018-08-15",

Pod_Time

The time at which the proof of delivery was created.

Data type:

Time

Parent tag:

Result

Child tag(s):

None.

<pod_time>20:45:01</pod_time>
 "pod_time": "20:45:01",

Bin_Date

The date on which the consignment was booked in to the system.

Data type:

Date

Parent tag:

Result

Child tag(s):

None.

<bin_date>2018-08-15</bin_date>
 "bin_date": "2018-08-15",

Bin_Time

The time at which the consignment was booked in to the Palletways system.

Data type:

Time

Parent tag:

Result

Child tag(s):

None.

<bin_time>20:45:01</bin_time>
 "bin_time": "20:45:01",

Bin_Contact

The name of the person (contact) associated with the booking in of the assignment.

Data type:

Alphanumeric. Free text field.

Parent tag:

Result

Child tag(s):

None.

<bin_contact>C.Wright</bin_contact>
 "bin_contact": "C.Wright",

Bin_Reference

A reference code associated with the booking in of the consignment.

Data type:

Alphanumeric. Free text field.

Parent tag:

Result

Child tag(s):

None.

<bin_reference>REF123456</bin_reference>
 "bin_reference": "REF123456",

NoteText

The text content of a note.

Data type:

Alphanumeric. Free text field.

Parent tag:

Result

Child tag(s):

None.

<note_text>Consignment is part of special case order.</note_text>
 "note_text": "Consignment is part of special case order.",

Status_Code

A code that indicates the status of the consignment.

Data type:

Alphanumeric. Free text field.

Parent tag:

Result

Child tag(s):

None.

<status_code>900</status_code>
 "status_code": "900",

Note_Group

The name of the note group that is associated with the note for the consignment.

Data type:

Alphanumeric. Free text field.

Parent tag:

Result

Child tag(s):

None.

<note_group>JIN</note_group>
 "note_group": "JIN",

Note_Type

The category of note associated with the consignment.

Data type:

Alphanumeric. Free text field.

Parent tag:

Result

Child tag(s):

None.

<note_type>IIN</note_type>
 "note_type": "IIN",

Create a System Note

At certain stages of the delivery process, your application will most likely need to update the consignment data. For example, your application may allow your drivers to provide status details about the delivery, such as 'freight delivered on 29 October 2017 and signed for by C Wright at 10:23'. This status information can be added to the Palletways system, and to do that, your application needs to create a system note.

To create a system note, your application needs to:

  1. Create note data that is in the appropriate format for the Palletways system. The data can be in XML or JSON. We have included an example of valid system note data for you to refer to. Your application needs to create and submit note data using the same tags and structure as shown in the example.

  2. Send the note data to the appropriate endpoint url, including the necessary parameters as part of the URL.

When the Palletways system receives note data, it validates it and provides a response. The response indicates whether the data is valid and whether it has been committed to the system as a new note. Your application needs to be able to process the various responses.

<?xml version="1.0" encoding="UTF-8"?>
<notes>
<header>
    <create_date>11/09/17</create_date>
    <create_time>13:46</create_time>
    <orig_filename>myfilename.xml</orig_filename>
    <notes_qty>2</notes_qty>
  </header>
  <note>
    <pw_id>31234567880</pw_id>
    <barcode>B1234ABCDE</barcode>
    <note_create_date>11/09/17</note_create_date>
    <note_create_time>13:45</note_create_time>
    <customer_name>CustomerName1</customer_name>
    <bin_ref>TheBinRef_1</bin_ref>
    <free_text>Free text for the first note</free_text>
    <note_group>JIN</note_group>
    <note_type>GIN</note_type>
    <note_description></note_description>
  </note>
  <note>
    <pw_id>31234567890</pw_id>
    <barcode>B1234ABCDF</barcode>
    <note_create_date>11/09/17</note_create_date>
    <note_create_time>13:46</note_create_time>
    <customer_name>CustomerName2</customer_name>
    <bin_ref>TheBinRef_2</bin_ref>
    <free_text>Free text for the second note</free_text>
    <note_group>JIN</note_group>
    <note_type>GIN</note_type>
    <note_description></note_description>
  </note>
</notes>
{
    "notes": {
        "header": {
            "create_date": "11/09/17",
            "create_time": "13:46",
            "orig_filename": "myfilename.xml",
            "notes_qty": "2"
        },
        "note": [
            {
                "pw_id": "31234567880",
                "barcode": "B1234ABCDE",
                "note_create_date": "11/09/17",
                "note_create_time": "13:45",
                "customer_name": "CustomerName1",
                "bin_ref": "TheBinRef_1",
                "free_text": "Free text for the first note",
                "note_group": "JIN",
                "note_type": "GIN",
                "note_description": ""
            },
            {
                "pw_id": "31234567890",
                "barcode": "B1234ABCDF",
                "note_create_date": "11/09/17",
                "note_create_time": "13:46",
                "customer_name": "CustomerName2",
                "bin_ref": "TheBinRef_2",
                "free_text": "Free text for the second note",
                "note_group": "JIN",
                "note_type": "GIN",
                "note_description": ""
            }
        ]
    }
}

Send a System Note to the Endpoint URL

To create a system note, your application needs to call the following URL:

https://api.palletways.com/createsystemnote

It also needs to append the URL with the create system note parameters. These parameters can be used with GET and POST methods.

Caution

If your application sends data with the commit parameter set to "true", the Palletways system will store the data as a 'live' instance (as long as it is valid). Once the data is 'live', it cannot be changed, and if it has been created by mistake, it will need to be deleted at the depot. For this reason, we recommend that you set the commit parameter to "false" when testing your application, and only set commit to "true" when you know that the data is complete and valid. When commit is "false", the Palletways system will validate the data and provide a response, but it will not store the data as a 'live' record in the system.

Responses to System Note Data

When you send system note data to the Palletways system, it provides a response to indicate whether the data is valid and has been stored. The possible responses vary, depending on whether the supplied data is valid and whether you included a commit parameter with a "true" value:

  • If your application provides valid data,  as valid XML or JSON, and sets the commit parameter to "false", the Palletways system responds with Successful (No data has been imported)

  • If your application provides valid data, as valid XML or JSON, and sets the commit parameter to "true", the Palletways system responds with Successful. Note Imported.

  • If your application provides invalid data, the Palletways system does not store the note and responds with Invalid Format.

System Note has Invalid Format

If your application sends a system note to the Palletways system, and the note is invalid, the Palletways system provides an invalid format response. The code in the system note is incorrect and so cannot be stored in the Palletways system. You will need to correct the code and then re-submit it for validation. For information on the correct syntax for the code, see Send a System Note to the Endpoint URL.

The Palletways system will not accept invalid data.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Status>
    <Code>ERROR_FORMAT_INVALID</Code>
    <Description>The supplied data could not be imported in the stated input format.</Description>
  </Status>
</Response>
Example currently unavailable.

System Note Successful, Not Committed

If your application sends system note data that is valid and the commit parameter is "false", the Palletways system will:

  • Store the note as a 'live' record

  • Provide a Successful. No Data Imported response. 

Your application has to be able to process the response from the Palletways system. We have included an example so that you can see the structure of the response.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Status>
    <Code>OK</Code>
    <Description>Successful</Description>
  </Status>
  <Detail>
    <Message>No data has been imported as it was not requested.</Message>
  </Detail>
</Response>
Example currently unavailable.

System Note Successful and Committed

When the Palletways system receives a valid system note 'with commit', it sends a Successful. Note Imported validation response. Receiving this response means that your system note is 'live' in the Palletways system.The Successful. Note Imported message is provided in XML or JSON, depending on what language you specified for the outputformat parameter (see Create a System Note).

Note

If your system note data is invalid, the Palletways system provides an Invalid Format response

Your application needs to be able to process the response from the Palletways system. We have provided an example of a successful response to a create note and commit request, so that you can see its structure.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Status>
    <Code>OK</Code>
    <Description>Successful</Description>
  </Status>
  <Detail>
    <ImportDetail>
      <ImportID>1</ImportID>
      <ResponseID>31234567880-1</ResponseID>
      <Information>Note for 31234567880 [JIN/GIN] imported.</Information>
    </ImportDetail>
    <ImportDetail>
      <ImportID>2</ImportID>
      <ResponseID>31234567890-2</ResponseID>
      <Information>Note for 31234567890 [JIN/GIN] imported.</Information>
    </ImportDetail>
  </Detail>
</Response>
Example currently unavailable.

Request a System Note

You can get your application to request consignment notes (called system notes) from the Palletways system. For example, if customers are asking where their deliveries are, you can request notes from the Palletways system to find out the status of the delivery.

To request system notes for a consignment, your application needs to call this URL:

https://api.palletways.com/getnotes

Your application also needs to set parameters, which have to be added to the end of the endpoint URL. Some of the parameters have to be added in a certain order.

The expected parameters are:

To specify which notes are required, your application can use the following parameters. These work in pairs, where the parameter with position 1 has to come first and must be immediately followed by the 'partner' parameter with position 2. For example, with the tracking id, the "trackingid" parameter has to be placed immediately before the tracking id number in the URL.

To specify the tracking ID:

To specify the consignment number:

To specify the date/time range:

To specify the delta ('since last update'):

When your application submits a system note request, the Palletways system sends a response.

Example:

https://api.palletways.com/getnotes/trackingid/30018513734

Example:

https://api.palletways.com/getnotes/conno/100-03186

Example:

https://api.palletways.com/getnotes/daterange/2017-07-20/11:45:00/2017-07-28/16:05:23

Example:

https://api.palletways.com/getnotes/delta/1493826173

Endpoint URL for System Note Request

To request system notes for a consignment, your application needs to call this URL:

https://api.palletways.com/getnotes

To specify which consignment notes are needed, the URL has to include various parameters.

Request System Note: Parameters

Your application also needs to set parameters, which have to be added to the end of the endpoint URL. Some of the parameters have to be added in a certain order.

The expected parameters are:

To specify which notes are required, your application can use the following parameters. These work in pairs, where the parameter with position 1 has to come first and must be immediately followed by the 'partner' parameter with position 2. For example, with the tracking id, the "trackingid" parameter has to be placed immediately before the tracking id number in the URL.

To specify the tracking ID:

To specify the consignment number:

To specify the date/time range:

To specify the delta ('since last update'):

When your application submits a system note request, the Palletways system sends a response.

Example:

https://api.palletways.com/getnotes/trackingid/30018513734

Example:

https://api.palletways.com/getnotes/conno/100-03186

Example:

https://api.palletways.com/getnotes/daterange/2017-07-20/11:45:00/2017-07-28/16:05:23

Example:

https://api.palletways.com/getnotes/delta/1493826173

Responses to System Note Requests

When your application makes a valid request for a system note, the Palletways system responds with the appropriate data, in the requested format. A valid request is a request that uses the correct endpoint URL, which includes appropriate parameters, a valid API key, and the output format.

Your application will need to be able to process the data that is returned. To illustrate the format of the data, we have included examples of returned system note data (both XML and JSON).

If your request is invalid, the Palletways system provides an error message. Typically, invalid requests are caused by your application:

  • Calling an incorrect URL

  • Using incorrect syntax in the URL

  • Including an invalid tracking ID in the URL

  • Including an invalid API key in the URL

For information on how to create a valid request, see Request a System Note.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Status>
    <Code>OK</Code>
    <Description>Successful</Description>
    <Count>1</Count>
  </Status>
  <Detail>
    <Data>
      <Manifest>
        <Date>2017-07-05</Date>
        <Time>19:14</Time>
        <Depot>
          <Number>19</Number>
          <Account>
            <Name>ALFRESCO CONCEPTS LTD</Name>
            <Code>Alfr01</Code>
            <Consignment>
              <Number>110664</Number>
              <TrackingID>30338302019</TrackingID>
              <Reference>110664</Reference>
              <Lifts>1</Lifts>
              <Weight>45</Weight>
              <HandBall>yes</HandBall>
              <TailLift>yes</TailLift>
              <Insurance>5000</Insurance>
              <CollectionDepot>19</CollectionDepot>
              <DeliveryDepot>37</DeliveryDepot>
              <BookInRequest>no</BookInRequest>
              <BookInContactName></BookInContactName>
              <BookInReference></BookInReference>
              <ManifestNote>Delivery expected Fri 7th July no access restrictions</ManifestNote>
              <Pallet>B00007225B</Pallet>
              <BillUnit>
                <Type>MQP</Type>
                <Amount>1</Amount>
              </BillUnit>
              <Service>
                <Type>Delivery</Type>
                <Code>B</Code>
                <Surcharge>B</Surcharge>
              </Service>
              <Address>
                <Type>Collection</Type>
                <ContactName></ContactName>
                <CompanyName>Alfresco Concepts</CompanyName>
                <Line>Garrood Drive</Line>
                <Line>FAKENHAM</Line>
                <Line>NORFOLK</Line>
                <Country>GB</Country>
                <PostCode>NR21 8NN</PostCode>
                <Telephone>01328012345</Telephone>
              </Address>
              <Address>
                <Type>Delivery</Type>
                <ContactName>Test Name</ContactName>
                <CompanyName>test Name</CompanyName>
                <Line>1 Long Street</Line>
                <Line>Big Town</Line>
                <Line>SUDBURY</Line>
                <Line>SUFFOLK</Line>
                <Country>GB</Country>
                <PostCode>CO10 8QD</PostCode>
                <Telephone>07777012345</Telephone>
              </Address>
            </Consignment>
          </Account>
        </Depot>
      </Manifest>
    </Data>
  </Detail>
</Response>
{
    "Status": {
        "Code": "OK",
        "Description": "Successful",
        "Count": 1
    },
    "Detail": {
        "Data": {
            "Manifest": {
                "Date": "2017-07-05",
                "Time": "19:14",
                "Depot": {
                    "Number": "19",
                    "Account": {
                        "Name": "ALFRESCO CONCEPTS LTD",
                        "Code": "Alfr01",
                        "Consignment": {
                            "Number": "110664",
                            "TrackingID": "30338302019",
                            "Reference": "110664",
                            "Lifts": "1",
                            "Weight": "45",
                            "HandBall": "yes",
                            "TailLift": "yes",
                            "Insurance": "5000",
                            "CollectionDepot": "19",
                            "DeliveryDepot": "37",
                            "BookInRequest": "no",
                            "BookInContactName": "",
                            "BookInReference": "",
                            "ManifestNote": "Delivery expected Fri 7th July no access restrictions",
                            "Pallet": [
                                "B00007225B"
                            ],
                            "BillUnit": [
                                {
                                    "Type": "MQP",
                                    "Amount": "1"
                                }
                            ],
                            "Service": [
                                {
                                    "Type": "Delivery",
                                    "Code": "B",
                                    "Surcharge": "B"
                                }
                            ],
                            "Address": [
                                {
                                    "Type": "Collection",
                                    "ContactName": "",
                                    "CompanyName": "Alfresco Concepts",
                                    "Line": [
                                        "Garrood Drive",
                                        "FAKENHAM",
                                        "NORFOLK"
                                    ],
                                    "Country": "GB",
                                    "PostCode": "NR21 8NN",
                                    "Telephone": "01328012345"
                                },
                                {
                                    "Type": "Delivery",
                                    "ContactName": "Test Name",
                                    "CompanyName": "Test Name",
                                    "Line": [
                                        "1 Long Street",
                                        "Big Town",
                                        "SUDBURY",
                                        "SUFFOLK"
                                    ],
                                    "Country": "GB",
                                    "PostCode": "CO10 8QD",
                                    "Telephone": "07777012345"
                                }
                            ]
                        }
                    }
                }
            }
        }
    }
}

Request Labels

You can use your application to request a label for a consignment. When your application makes the request, the Palletways system matches the information in the request to a consignment in the system. It then returns the label as PDF data. You can set your application to forward the PDF data to a printer or another system so that the label can be printed out and added to the delivery.

Each label contains information about the delivery and a barcode. The Palletways system uses the barcode to track the consignment as it progresses through our delivery network.

Send a Get Label Request to the End Point URL

To get the label data for a consignment in the Palletways system, your application needs to send a request to the following URL:

https://api.palletways.com/method

Where method is one of the GetLabels methods:

Both methods require the Palletways system to find a consignment based on information provided in the request. You can use either method, depending on what information you want your application to provide.

The request also needs to append the URL with the GetLabels parameters and the encrypted API key for the user's account. These parameters can be used with GET and POST methods.

getLabelsById

Use the getLabelsById method to send a request for a consignment label. The request needs to contain the identification number of the consignment. You can also rotate the label by providing the degrees as a second parameter.

https://api.palletways.com/getLabelsById/99999918050857?apikey=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Where:

99999918050857 is an example consignment ID. Replace this with the appropriate ID for your consignment.

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX is the encrypted application key of the current user. Replace this with your api key.

getLabelsByConNo

Use the getLabelsByConNo method to send a request for a consignment label. The request needs to contain the number of the consignment (as stored in the Palletways system). 

https://api.palletways.com/getLabelsByConNo/99999918050857?apikey=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Where:

99999918050857 is an example consignment number. Replace this with the appropriate number for your consignment.

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX is the encrypted application key of the current user. Replace this with your api key.

Responses to Get Label Requests

The Palletways system responds to requests that use the GetLabel methods (GetLabelsbyId and GetLabelsbyConNo) with PDF data for a label.

If the request is successful, the label contains the consignment information. 

An example of a label returned by a successful label request.

But if the request is unsuccessful, for example, due to incorrect syntax of the request, the label contains an error message.

error-label-pdf.png

Request a Proof of Delivery Image

You can use your application to request an image of the proof of delivery document for a consignment. When your application makes the request, the Palletways system matches the information in the request to a consignment in the system. It then returns the proof of delivery as PDF data. You can set your application to forward the PDF data to a printer or another system so that the proof of delivery can be printed out.

Each proof of delivery document contains the delivery details, including the date of delivery and signatures. 

To request a proof of delivery image, you need to set your application to send a getPODByTrackingId request. The Palletways system will then send a response as PDF data.

Send a POD Request to the Endpoint URL

To request a proof of delivery for a consignment, your application needs to call this URL:

https://api.palletways.com/getPodByTrackingId

Where getPodByTrackingId is the method. 

You need to add the getPodByTrackingId parameters and the encrypted API key to the end of the URL. The parameters can be used with GET and POST methods.

The expected parameters are:

https://api.palletways.com/getPodByTrackingId/99999918050857?apikey=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Where:

99999918050857 is an example tracking number. Replace this with the appropriate tracking number for your consignment.

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX is the encrypted application key of the current user. Replace this with your api key.

Responses to POD Requests

When your application requests a proof of delivery image, the Palletways system responds by sending PDF data. 

If the request is valid and successful, the PDF is the proof of delivery document and you can direct this to a printer for printing or save it to a system.

podimage-example.png

If the request is invalid, the PDF contains an error message.

Request Available Services

You can set your application to request a list of the available collection or delivery services for a pallet. The Palletways system responds to the request by providing a list of available services.

You can set your application to query for available services, and then present the list of options. For example, you could display the list of options on a Form. When one of the services is selected, you can set your application to create a consignment and use the service that has been chosen. 

To request the available services, you need your application to send a request to the endpoint URL. The request needs to use the availableServices method.

The Palletways system will respond to a successful request with a list of available services. If the request is unsuccessful, the system returns an error message.

Available Services Endpoint URL

To get the list of available services for delivery, you need to set your application to send a request to the following  URL:

https://api.palletways.com/availableServices/

Where availableServices is the method for requesting a list of services. You also need to append the URL with the availableServices parameters, the encrypted API key for the user account, and the output format. These parameters can be used with GET and POST methods.

When the request is made, the Palletways system will send a response

https://api.palletways.com/availableServices/3/GB/BB4%206HH/GB/BB4%205HU?apikey=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&output=json

Where:

3 is the type of consignment, in this case third party.

GB is the from country, in this case Great Britain.

BB4%205HU is the from post code, in this case BB4 5HU.

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX is the encrypted application key of the current user. Replace this with your api key.

output=json sets the output type as JSON. You could use output=xml for XML output.

Responses to Available Services Requests

If your application makes a valid request using the availableServices method, the Palletways system responds with a list of available services for the consignment. The response contains tags that provide information about each service.

The Palletways system returns an error message if the request is invalid.

<Response>
 <Status>
  <Code>OK</Code>
  <Description>Successful</Description>
  <Count>16</Count>
 </Status>
 <Detail>
  <Data>
   <id>26</id>
   <ServiceGroupCode>B</ServiceGroupCode>
   <ServiceCode>D</ServiceCode>
   <ServiceName>ECONOMY COLLECTION 48 HOUR</ServiceName>
   <ServiceGroupName>ECONOMY</ServiceGroupName>
   <ServiceDaysMin>2</ServiceDaysMin>
   <ServiceDaysMax>2</ServiceDaysMax>
   <ServiceType>Collection</ServiceType>
   <Label_Shed>K</Label_Shed>
  </Data>
  <Data>
   <id>942</id>
   <ServiceGroupCode>F</ServiceGroupCode>
   <ServiceCode>T</ServiceCode>
   <ServiceName>CURTAINS</ServiceName>
   <ServiceGroupName>FREE SERVICES</ServiceGroupName>
   <ServiceDaysMin>3</ServiceDaysMin>
   <ServiceDaysMax>3</ServiceDaysMax>
   <ServiceType>Collection</ServiceType>
   <Label_Shed>K</Label_Shed>
  </Data>
  <Data>
   <id>941</id>
   <ServiceGroupCode>F</ServiceGroupCode>
   <ServiceCode>S</ServiceCode>
   <ServiceName>DAMAGE RETURNS</ServiceName>
   <ServiceGroupName>FREE SERVICES</ServiceGroupName>
   <ServiceDaysMin>3</ServiceDaysMin>
   <ServiceDaysMax>3</ServiceDaysMax>
   <ServiceType>Collection</ServiceType>
   <Label_Shed>K</Label_Shed>
  </Data>
 </Detail>
</Response>
{
  "Response": {
    "Status": {
      "Code": "OK",
      "Description": "Successful",
      "Count": "16"
    },
    "Detail": {
      "Data": [
        {
          "id": "26",
          "ServiceGroupCode": "B",
          "ServiceCode": "D",
          "ServiceName": "ECONOMY COLLECTION 48 HOUR",
          "ServiceGroupName": "ECONOMY",
          "ServiceDaysMin": "2",
          "ServiceDaysMax": "2",
          "ServiceType": "Collection",
          "Label_Shed": "K"
        },
        {
          "id": "942",
          "ServiceGroupCode": "F",
          "ServiceCode": "T",
          "ServiceName": "CURTAINS",
          "ServiceGroupName": "FREE SERVICES",
          "ServiceDaysMin": "3",
          "ServiceDaysMax": "3",
          "ServiceType": "Collection",
          "Label_Shed": "K"
        },
        {
          "id": "941",
          "ServiceGroupCode": "F",
          "ServiceCode": "S",
          "ServiceName": "DAMAGE RETURNS",
          "ServiceGroupName": "FREE SERVICES",
          "ServiceDaysMin": "3",
          "ServiceDaysMax": "3",
          "ServiceType": "Collection",
          "Label_Shed": "K"
        }
      ]
    }
  }
}

Available Services Tags

The Palletways system returns the following tags in its response to a valid availableServices request. 

ServiceGroupCode

A code that represents the category of Palletways collection/delivery service, for example, PREMIUM. For more information on the codes, see Palletways Service Codes.

Data type:

Alphanumeric. Free text field.

Parent tag:

Service

Child tag(s):

None.

<ServiceGroupCode>B</ServiceGroupCode>
"ServiceGroupCode": "B",

ServiceCode

A code that represents the type of Palletways collection/delivery service, see Palletways Service Codes.

Data type:

Alphanumeric. Free text field.

Parent tag:

Service

Child tag(s):

None.

<ServiceCode>B</ServiceCode>
"ServiceCode": "B",

ServiceName

The name of the Palletways collection/delivery service, for example, ECONOMY COLLECTION. For more information on the names, see Palletways Service Codes.

Data type:

Alphanumeric. Free text field.

Parent tag:

Service

Child tag(s):

None.

<ServiceName>ECONOMY COLLECTION</ServiceName>
"ServiceName": "ECONOMY COLLECTION",

ServiceGroupName

The name of the category of Palletways collection/delivery service, for example, PREMIUM. For more information on the names, see Palletways Service Codes.

Data type:

Alphanumeric. Free text field.

Parent tag:

Service

Child tag(s):

None.

<ServiceGroupName>PREMIUM</ServiceGroupName>
"ServiceGroupName": "PREMIUM",

ServiceDaysMin

The minimum number of days needed to provide the service.

Data type:

Numeric positive whole number.

Parent tag:

Service

Child tag(s):

None.

<ServiceDaysMin>2</ServiceDaysMin>
"ServiceDaysMin": "2",

ServiceDaysMax

The maximum number of days needed to provide the service.

Data type:

Numeric positive whole number.

Parent tag:

Service

Child tag(s):

None.

<ServiceDaysMax>4</ServiceDaysMax>
"ServiceDaysMax": "4",

ServiceType

The type of service that can be provided. This can be collection, delivery , or thirdparty (for when another company provides the service).

Data type:

Alphanumeric. Free text field.

Parent tag:

Service

Child tag(s):

None.

<ServiceType>delivery</ServiceType>
"ServiceType": "delivery",

Label_Shed

The physical consignment is transported via a shed at the depot . The label_shed information shows which of the sheds is used for this consignment.

Data type:

Alphanumeric. Free text field.

Parent tag:

Service

Child tag(s):

None.

<Label_Shed>K</Label_Shed>
"Label_Shed": "K",

Request an Outbound Manifest

You can get your application to request an outbound manifest from the Palletways system. The manifest is a list of the all the pallets that have to be collected from a central depot and transported to another depot in the network, ready for delivery. 

The outbound manifest list contains details of the number of pallets to be collected from a depot and also the destinations for delivery.

To get your application to request an outbound manifest, it needs to send a manifest request to the endpoint URL

The Palletways system will then respond with the list data (if the request is successful) or error information if there is a problem with the request.

Manifest Request Endpoint URL

To get the manifest data for a consignment in the Palletways system, your application needs to send a request to the following URL:

https://api.palletways.com/obman/

Where obman is the method for requesting a manifest. You also need to append the URL with the obman parameters and the encrypted API key for the depot. These parameters can be used with GET and POST methods.

https://api.palletways.com/obman/20180814?apikey=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Where:

20180814 is an example date, in this case, August 14 2018. Replace this with the date for the manifest you want to request.

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX is the encrypted application key of the depot. Replace this with your depot api key.

Responses to Manifest Requests

If your application makes a valid manifest request to the Palletways system, the system will return a list in XML or JSON format. 

If the manifest request is invalid, the Palletways system returns an error message.

<Response>
 <Status>
  <Code>OK</Code>
  <Description>Successful</Description>
  <Count>20</Count>
 </Status>
 <Detail>
  <Data>
   <dc_syscon>30264424750</dc_syscon>
   <d_shift-asn>2018-08-13</d_shift-asn>
   <i_sysxsn>182260848</i_sysxsn>
   <c_transaction>D</c_transaction>
   <i_syscarrier>4</i_syscarrier>
   <c_account>319750</c_account>
   <c_carcon>2271669</c_carcon>
   <c_cusref>2271669</c_cusref>
   <i_sunits>1</i_sunits>
   <dc_weight>77</dc_weight>
   <c_insure/>
   <i_pay-syscardep>617999</i_pay-syscardep>
   <i_syscardep>617999</i_syscardep>
   <c_c-round>617999</c_c-round>
   <c_service/>
   <i_c-sysaddress>159007750</i_c-sysaddress>
   <i_d-sysaddress>191071750</i_d-sysaddress>
   <l_c-business>yes</l_c-business>
   <i_d-syscardep>717999</i_d-syscardep>
   <c_d-round>717999</c_d-round>
   <i_d-syscarrier>19999</i_d-syscarrier>
   <c_d-service>B</c_d-service>
   <c_d-surcharge>M</c_d-surcharge>
   <l_d-business>yes</l_d-business>
   <d_duedate>2018-08-20</d_duedate>
   <i_duetime>63000</i_duetime>
   <c_c-surcharge/>
   <c_insurance>ADSP</c_insurance>
   <l_handball>no</l_handball>
   <l_taillift>yes</l_taillift>
   <c_physical>PL</c_physical>
   <l_bin>no</l_bin>
   <l_printed>no</l_printed>
   <l_barcodes>yes</l_barcodes>
   <l_image>no</l_image>
   <l_binrequest>yes</l_binrequest>
   <c_binContact/>
   <c_bin/>
   <c_accname>D50 (Yankee) DE</c_accname>
   <l_DelPaper>no </l_DelPaper>
   <for_i_syscardep>717999</for_i_syscardep>
   <for_DepotNumber>396</for_DepotNumber>
  </Data>
 </Detail>
</Response>
{
  "Response": {
    "Status": {
      "Code": "OK",
      "Description": "Successful",
      "Count": "20"
    },
    "Detail": {
      "Data": {
        "dc_syscon": "30264424750",
        "d_shift-asn": "2018-08-13",
        "i_sysxsn": "182260848",
        "c_transaction": "D",
        "i_syscarrier": "4",
        "c_account": "319750",
        "c_carcon": "2271669",
        "c_cusref": "2271669",
        "i_sunits": "1",
        "dc_weight": "77",
        "i_pay-syscardep": "617999",
        "i_syscardep": "617999",
        "c_c-round": "617999",
        "i_c-sysaddress": "159007750",
        "i_d-sysaddress": "191071750",
        "l_c-business": "yes",
        "i_d-syscardep": "717999",
        "c_d-round": "717999",
        "i_d-syscarrier": "19999",
        "c_d-service": "B",
        "c_d-surcharge": "M",
        "l_d-business": "yes",
        "d_duedate": "2018-08-20",
        "i_duetime": "63000",
        "c_insurance": "ADSP",
        "l_handball": "no",
        "l_taillift": "yes",
        "c_physical": "PL",
        "l_bin": "no",
        "l_printed": "no",
        "l_barcodes": "yes",
        "l_image": "no",
        "l_binrequest": "yes",
        "c_accname": "D50 (Yankee) DE",
        "l_DelPaper": "no ",
        "for_i_syscardep": "717999",
        "for_DepotNumber": "396"
      }
    }
  }
}

Data Types

Data types are the expected values for each field.

Palletways Service Codes

For information on service codes, refer to the appropriate category:

Premium Services:

Premium Delivery Services

Premium Collection Services

European Premium Delivery Services

Economy Services:

Economy Delivery Services

Economy Collection Services

European Economy Delivery Services

Irish Services:

Irish Delivery Services

Premium Delivery Services

Premium Collection Services

European Premium Delivery Services

Economy Delivery Services

Economy Collection Services

European Economy Delivery Services

Irish Delivery Services

Consignment Types

Palletways has three main job types that you will be submitting into the system. Each are very different and will define what services you can select.

  • Delivery

    A delivery is the typical job type most users will select. This involves pallets that are collected from the customer premises, processed by the network, and then delivered to a specified location. Use a delivery when sending freight out.

  • Collection

    A collection is when pallets are collected from a specified address, processed through the Palletways network, and then delivered to the customer. The pallets are delivered by the customer's local Palletways depot. Use a collection when freight is being returned to you.

  • Third Party

    A third party is when the physical freight is never handled by you or your local Palletways depot. You arrange another member of the network to collect pallets and process them through the network. The pallets are then  delivered by another member without the freight ever arriving at your premises.

Pallet Types

Palletways uses the following types of pallets: