Custom shipping method via JSON push
This page is about the old "JSON push" method for creating a custom shipping method. For new integrations, we recommend Custom shipping method.
In Picqer we provide some integrated shipping providers. When you want to connect with another shipping provider, you can create your own webservice and link it in Picqer. This way you can create your own 'Create shipment' button in Picqer.
Create a new JSON Push shipping provider Enter the Endpoint URL of your webservice. You can optionally choose to provide a username and password. Picqer will use those to authenticate with Auth Basic method.
When a user creates a shipment, we send a request to your endpoint with JSON data in the body. We provide the address data of the customer and the products of this order. Picqer expects a JSON response with a track and trace code and a PDF of the shipping label as a base64 encoded string.
When we send you the shipment request, you have 15 seconds to respond with the shipment details. Otherwise Picqer will show the request as failed and the user can send a new request.
This is an example of the request we send to your endpoint when the user creates a shipment.
POST
https://your-endpoint-url.com
{
"picklist": {
"idpicklist": 36000000,
"picklistid": "20211008",
"idcustomer": 21000000,
"idorder": 50000000,
"idreturn": null,
"idwarehouse": 13,
"idtemplate": 2,
"idshippingprovider_profile": 5000,
"deliveryname": "Alyssa de Roos",
"deliverycontact": null,
"deliveryaddress": "Winklaarlaan 1-3",
"deliveryaddress2": null,
"deliveryzipcode": "2544KR",
"deliverycity": "Zuid-Beijerland",
"deliveryregion": "Zuid-Holland",
"deliverycountry": "NL",
"telephone": "",
"emailaddress": "",
"reference": null,
"assigned_to_iduser": null,
"invoiced": false,
"urgent": true,
"preferred_delivery_date": null,
"status": "new",
"totalproducts": 6,
"totalpicked": 6,
"snoozed_until": null,
"closed_by_iduser": null,
"closed_at": null,
"created": "2021-03-31 10:56:16",
"updated": "2021-03-31 10:56:17",
"idfulfilment_customer": 109,
"products": [
{
"idpicklist_product": 87647456,
"idproduct": 15474932,
"idorder_product": 124828808,
"idreturn_product_replacement": null,
"idvatgroup": 7372,
"productcode": "Samenstelling",
"name": "samenstelling",
"remarks": "",
"amount": 3,
"amountpicked": 0,
"amount_picked": 0,
"price": 0,
"weight": 0,
"stocklocation": null,
"stock_location": null,
"partof_idpicklist_product": null,
"has_parts": true
},
{
"idpicklist_product": 87647457,
"idproduct": 14653706,
"idorder_product": 124828811,
"idreturn_product_replacement": null,
"idvatgroup": 7372,
"productcode": "AC582010",
"name": "Cisco 1080i Replacement Replacement Tripple",
"remarks": null,
"amount": 3,
"amountpicked": 3,
"amount_picked": 3,
"price": 0,
"weight": 688,
"stocklocation": "A.1.1.3, A.1.1.5, A.5.5.3",
"stock_location": "A.1.1.3, A.1.1.5, A.5.5.3",
"partof_idpicklist_product": 87647456,
"has_parts": false
},
{
"idpicklist_product": 87647458,
"idproduct": 14653740,
"idorder_product": 124828812,
"idreturn_product_replacement": null,
"idvatgroup": 7372,
"productcode": "AG108311",
"name": "3com Blue LZ20",
"remarks": null,
"amount": 3,
"amountpicked": 3,
"amount_picked": 3,
"price": 0,
"weight": 1700,
"stocklocation": "A.1.1.3, A.4.7.1",
"stock_location": "A.1.1.3, A.4.7.1",
"partof_idpicklist_product": 87647456,
"has_parts": false
}
]
},
"weight": 7164,
"worth": 0,
"sender": {
"name": "Picqer B.V.",
"contactname": "Casper Bakker",
"address": "Meander 601",
"address2": null,
"zipcode": "6825ME",
"city": "Arnhem",
"region": null,
"country": "NL"
},
"recipient": {
"name": "Alyssa de Roos",
"contactname": null,
"address": "Winklaarlaan 1-3",
"address2": null,
"zipcode": "2544KR",
"city": "Zuid-Beijerland",
"region": "Zuid-Holland",
"country": "NL"
},
"reference": "20211008",
"pickup_point_data": null,
"user": {
"iduser": 400,
"idpacking_station": 800,
"username": "stephan",
"firstname": "Stephan",
"lastname": "Groen",
"first_name": "Stephan",
"last_name": "Groen",
"emailaddress": "example@picqer.com",
"language": null,
"admin": true,
"active": true,
"last_login_at": "2021-03-31 10:54:42",
"created_at": "2013-12-19 13:47:13",
"updated_at": "2021-03-31 10:54:42"
}
}
HTTP/1.1 200 OK
{
"identifier": "3SAPPL80237480",
"trackingurl": "https://example.com/shipment/3SAPPL80237480",
"carrier_key": "postnl",
"label_contents_pdf": "--BASE64 ENCODED VERSION OF PDF--",
"label_contents_zpl": "--BASE64 ENCODED VERSION OF ZPL--"
}
These are the attributes that you can (or must) supply in your response. Your response must always have a 200 OK status, otherwise we will handle the call as failed.
| Name |
Type |
Required |
Description |
| identifier |
string |
required |
Shipper's identifier of the shipment, like the trackingcode |
| trackingurl |
string |
optional |
URL of track and trace page |
| carrier_key |
string |
optional |
Key of the carrier, so Picqer can show the right logo. See available options below |
| label_contents_pdf |
string |
required |
Base64 encoded PDF document of label |
| label_contents_zpl |
string |
optional |
Base64 encoded ZPL document of label |
With a carrier key, Picqer knows wich carrier will deliver the package. We use this for example to show the logo of the carrier next to a shipment and for letting webshops know who the carrier is.
See a list of the available carrier keys
This is case-sensitive. Make sure you provide the carrier key in lowercase letters.
We always need a PDF version of the shipping label, but besides the PDF you can also provide a ZPL version of the label. If the printer supports ZPL, we will use the ZPL version of the label for improved print quality.
Whenever you respond with another status than 200 OK, we will show an error message to the user. If you can, please provide a human-readable error message for the user.
If an error occurred, return a 400 or 500 status code with a JSON body with an 'error' key. Like this:
HTTP/1.1 400 Bad Request
{
"error": "Shipping method is not allowed for recipient country Belgium."
}
Picqer will show the given error message to the user.
If the delivery address is outside the EU Customs Zone, the request will also include customs_data with customs information of the products.
POST
https://your-endpoint-url.com
{
"picklist": {
"idpicklist": 105503,
"picklistid": "20140079",
...
},
"weight": 0,
"worth": 10,
"sender": {
...
},
"recipient": {
...
},
"customs_data": {
"products": [
{
"idproduct":6485,
"productcode":"HEJUE",
"description":"Optische toslink kabel",
"amount":3,
"value":12.59,
"total_value":37.77,
"weight":120,
"hs_code":"287133",
"country_of_origin":"CN"
}
]
}
}
