Technical details for custom and external shipping providers

Custom and external shipping providers work technically the same. The difference is that custom shipping providers can be configured by yourself in your Picqer account, and external shipping providers are configured by Picqer for all Picqer users.

These are the technical details for both methods.

Pre-requisites

To configure the integration we need the following:

Name of the shipping provider
URL endpoint for the configuration options (optional)
URL endpoint to create a label
Authentication method via username and password or via API key

We currently only support HTTP Basic Auth for authentication. For the endpoints we currently only support HTTPS connections with TLS 1.1 or later.

We have an example PHP script that implements both endpoints..

Configuration options

This is optional. If you don't provide a configuration URL, there will be no options for the user when adding shipping profiles.

To retrieve the configuration options, we send a GET request with authentication from the user's credentials. We expect to receive all possible configurations for the chosen customer in return.

For each shipment, we will send along which configuration the customer has selected.

GET https://example.com/picqer-integration/config-options

HTTP/1.1 200 OK { "version": "1.0", "data": { "items": [ { "key": "shipping_method", "label": "Shipping method", "description": null, "type": "list", "possible_values": [ { "value": 29, "label": "DHLForYou" }, { "value": 928, "label": "DPD Global" } ], "default_value": 928, "required": true }, { "key": "sender_address", "label": "Sender", "description": "Used as sender address on label", "type": "list", "possible_values": [ { "value": 92828, "label": "Picqer B.V., Meander 601, Arnhem" }, { "value": 273682, "label": "Karwei, Delta 39, Arnhem" } ], "default_value": 92828 }, { "key": "insured", "label": "Insured", "description": null, "type": "list", "possible_values": [ { "value": 0, "label": "No" }, { "value": 1, "label": "Yes" } ], "default_value": 1 }, { "key": "pickup_instructions", "label": "Pickup instructions", "description": null, "type": "text", "default_value": null } ] } }

In this example you see 4 fields which we will show in the configuration of the profile.

key: This is the key with which we send back the data to you when creating a shipment.
label: This is what we show to the user for this configuration option.
description: Optional, gives the user additional explanation about this option.
type: "text" for a free text field or "list" for a list of options from which the user can choose.
possible_values: If the type is "list", you can provide the options here.
default_value: The standard value we will use if no other is chosen.

Creating a shipment

Once the user has created 1 or multiple profiles, they can use these to create a shipment.

When the user creates a shipment, we send a POST request to the URL you have provided. In this request you will receive the chosen options of the profile and details about the shipment. We expect a shipping label in PDF (mandatory) and optionally a ZPL file along with the tracking code and URL in return.

We ensure that the label is automatically printed and that the tracking data is sent to the customer.

POST to for example:

POST https://example.com/picqer-integration/shipments

{ "version": "1.0", "data": { "profile": [ { "key": "shipping_method", "value": 29 }, { "key": "sender_address", "value": 92828 }, { "key": "insured", "value": 0 }, { "key": "pickup_instructions", "value": null } ], "shipment": { "weight": 29388, "total_paid": 291.29, "value_of_goods": 199.99, "recipient": { "name": "Picqer B.V.", "contactname": null, "address": "Meander 251", "address2": null, "zipcode": "6825MC", "city": "Arnhem", "region": "Gelderland", "country": "nl", "emailaddress": "info@picqer.com", "telephone": null }, "references": { "reference": "wintersjaal #8928283", "idorder": 2832123, "idreturn": null, "idpicklist": 63832123, "orderid": "O2018-29230", "returnid": null, "picklistid": "P2018-29382" }, "preferred_delivery_date": "2018-09-09", "pickup_point_data": [], "language": "nl" } } }

First you will receive the chosen configuration options of the profile in "profile".

After that, in the shipment, you will receive the required fields to create a shipment.

Fields that do not speak for themselves are:

weight: Weight in grams.
total_paid: Price the customer has paid for the products in this shipment.
value_of_goods: The purchase value of the products in the shipments, often used for insurance.
references: All optional, you can use references.reference to send the reference to the receiver.
preferred_delivery_date: Can be used if the customer has submitted a preferred delivery date. Can be 'null' when unused.
pickup_point_data: This is an array or object. When there is no pickup_point_data available this will be an empty array (Note: This differs from the "orders" endpoint in the Picqer API). The information in this key depends on the carrier. We strongly encourage you to read the examples page.
language: Preferred language of communication with the customer, currently only available in "nl" or "en".

{ "version": "1.0", "data": { "carrier_key": "postnl", "carrier_name": "PostNL", "tracking_code": "xx", "tracking_url": "https://example.com/XX", "label": { "format": "A6", "documents": { "pdf": "--BASE64 ENCODED VERSION OF PDF--", "zpl": "--BASE64 ENCODED VERSION OF ZPL--" } } } }

The processing of the request should take a maximum of 20 seconds, otherwise we will regard this shipment as failed.

carrier_key: Not mandatory, but it makes it easier to map the selected shipping provider to the online stores and marketplaces such as Amazon and Bol.com. See a list of the available carrier keys
carrier_name: The name of the shipping provider as it will be shown to the end customer.
tracking_code: (optional, but desired) The tracking code of the shipment.
tracking_url: (optional) The URL to the public status page of this shipment.
label.format: The physical format of the label, currently we only support 'A6' and ‘A4’ size. Only use ‘A4’ if the label does not fit in ‘A6’ size, like with customs documents.
label.documents.pdf: Base64 encoded version of the PDF with the shipping label.
label.documents.zpl: (optional) Base64 encoded version of the ZPL of the shipping label.

We always need a PDF version of the label in Picqer. Therefore this is mandatory. Optionally you can also provide the ZPL, which we use when printing on printers that support ZPL.

Errored response

When you send an HTTP Status Code within the 4xx range, we will pick up the error message and show it to the user. You can do this in the format as follows:

{ "version": "1.0", "error_messages": [ "Recipient country not allowed for this product.", "Zip code invalid for country NL" ] }

Responses with a status code in the 5xx range will trigger a generic response in Picqer, this should not be used in regular circumstances.

Customs information

If the country of the recipient is outside the EU customs union, you will receive the field ‘customs_data’ in the shipment in which data about the products of the shipment can be found. You can send us an A4 document with the shipping label/CN23 form, commercial invoice and any other customs documents in return.

Example with customs information:

{ "version": "1.0", "data": { "profile": [ { "key": "shipping_method", "value": 29 }, { "key": "sender_address", "value": 92828 }, { "key": "insured", "value": 0 }, { "key": "pickup_instructions", "value": null } ], "shipment": { "weight": 29388, "total_paid": 291.29, "value_of_goods": 199.99, "recipient": { "name": "Picqer B.V.", "contactname": null, "address": "Meander 251", "address2": null, "zipcode": "6825MC", "city": "Geneva", "region": null, "country": "CH", "emailaddress": "info@picqer.com", "telephone": null }, "references": { "reference": "wintersjaal #8928283", "idorder": 2832123, "idreturn": null, "idpicklist": 63832123, "orderid": "O2018-29230", "returnid": null, "picklistid": "P2018-29382" }, "preferred_delivery_date": "2018-09-09", "pickup_point_data": [], "language": "nl", "customs_data": { "products": [ { "description": "Philips Hue Duo Pack", "amount": 2, "weight": 350, "value": 29.99, "hs_code": "288392", "country_of_origin": "CN" }, { "description": "Philips Hue Remote", "amount": 1, "weight": 150, "value": 49.95, "hs_code": "928382", "country_of_origin": "CN" } ] } } } }

Send all customs documents as A4 label document in return and also mention you use the A4 format. Picqer will then automatically select the correct printer.

Example of your response:

{ "version": "1.0", "data": { "carrier_key": "postnl", "carrier_name": "PostNL", "tracking_code": "xx", "tracking_url": "https://example.com/XX", "label": { "format": "A4", "documents": { "pdf": "--BASE64 ENCODED VERSION OF PDF--" } } } }

You can only send 1 PDF document in return. If multiple documents need to be printed, like with customs information, all documents should be submitted to Picqer in 1 PDF document.

If no customs documents need to be included, you can also respond with an A6 format label.