Packator API

Service Url

Production: https://api.packator.com
Staging: https://staging-api.packator.com

Authorization

You’ll need a personal API Key and APP Secret if you want to use the API to access you own Packator data - for example you want create new Job request or to get the list of all Jobs you have generated.

With each request, you’ll be sending ‘Authorization’ header using Basic flow and base64 encoded ‘appKey:appSecret’.

Example:

curl
-s https://api.packator.com/api/v2.6/job
-h 'Authorization: Basic appKey:appSecret’

Entities

You’ll need a personal API Key and APP Secret if you want to use the API to access you own Packator data - for example you want create new Job request or to get the list of all Jobs you have generated.

With each request, you’ll be sending ‘Authorization’ header using Basic flow and base64 encoded ‘appKey:appSecret’.

Example:

curl
-s https://api.packator.com/api/v2.6/job
-h 'Authorization: Basic appKey:appSecret’

Address

Property
Type
Description
street
string
Street Name
streetNo
string
Street Number
city
string
City Name
countryCode
string
geolocation
geolocation
ISO 3166-1 alpha-2
string
postalCode
string
Address Geolocation
addressLine2
Address Postal Code

Geolocation

Property
Type
Description
lat
number
lng
number

Contact

Property
Type
Description
name
string
Contact Name
phone
string
Contact Phone Number
companyName
string
Contact Company Name

Price

Property
Type
Description
total
number
Total price including Vat
totalExcludingVat
number
Total price excluding Vat
vat
number
Total Vat
vatRate
string
Vat rate e.g “19%”
components
PriceComponent[]
Price Components

Price Component

Property
Type
Description
type
string
Type of price component e.g. “packaging_price”
label
number
Text label for the price component
price
string
Total price for component including Vat
mandatory
boolean
Gives information if price component is mandatory or not. If mandatory, customers cannot choose to turn in on or or off (example “Service Price”). If not mandatory, customers can turn it on or off (example optional “gift wrap”).
applied
boolean
Gives information if price component is applied or not. If mandatory=true then applied is always true.

Delivery Delay

Property
Type
Description
from
integer
Earliest delivery
to
string
Latest delivery
precision
integer
‘hours’ or ’days’. For example if from is 1 and to is 2 and precision is ‘hours’ it means delivery will be 1 or 2 hours from the pickup. Similar is for ‘days’.
estimate.from
date
Earliest delivery calculation. Requested pickup date is taken as base date and ‘from’ delay is added (hours or days)
estimate.to
date
string
Latest delivery calculation. Requested pickup date is taken as base date and ‘to’ delay is added (hours or days)
Same as precision
estimate.precision

Product Size

Property
Type
Description
height
number
Height of the parcel (in cm)
length
number
Length of the parcel (in cm)
width
number
Width of the parcel (in cm)

Pickup Timeframe

Property
Type
Description
from
DateTime
Start of the timeframe when driver will come to pick up parcel (earliest pickup). Format:‘2017-01-24T09:00:00.000Z’
to
DateTime
End of the timeframe when driver will come to pick up parcel (latest pickup). Format:‘2017-01-24T09:00:00.000Z’
pickupDate
DateTime
Pickup DateTime that will be communicated to drivers as the latest pickup DateTime.

Payment

Property
Type
Description
type
string
Allowed values are ‘account’ or ‘credit-card’.
nonce
string
Braintree nonce. Used if payment.type is ‘credit-card’. Cannot be used together with ‘token’.
token
string
Braintree token. Used if payment.type is ‘credit-card’. Cannot be used together with ‘nonce’.

Driver

Property
Type
Description
id
string
Hero unique identifier
name
string
Hero name
email
string
Hero email

Product

Property
Type
Description
id
string
Unique identifier of the product
type
string
s, m, l
deliveryDelay
DeliveryDelay
Possible delivery delay in days
maxDimensions
ProductSize
dimensions
Maximum dimensions for the parcel
ProductSize
maxWeight
number
Actual dimensions if sent in request
number
weight
Maximum weight fo the parcel
Actual weight if sent in request
price
string
Object containing price details
Price
service
Service name
Date
Date
Latest possible pickup time for the requested date
latestPickupTime
earliestPickupTime
Earliest possible pickup time for the requested date

Delivery

Property
Type
Description
by
string
Internal information if delivery is done via Hubs or directly
isExternallyShipped
string
Information if job is shipped using external partner services
serviceType
boolean
Type of the service (e.g. EASY-ECONOMY)
estimatedTime.from
Date
Datetime of earliest delivery
estimatedTime.to
Date
Datetime of latest delivery
estimatedTime.precision
string
‘hours’ or ‘days’

Job

Property
Type
Description
id
string
Job unique identifier
userId
string
Customer Id
key
string
Job 5-6 code string
offerId
string
If job is created out of special offer, offerId will be written in this property
status
string
Job Status
pickup.address
Address
pickup.contact
Contact
pickup.date
pickup.timeframe
Legacy, pickup.date equal to pickup.timeframe.pickupDate
DateTime
destination.address
Timeframe in which Hero will come to pickup the parcel
destination.contact
PickupTimeframe
package.type
package.image
Address
package.maxDimensions
s, m, l, oversized
package.maxWeight
Contact
If customer uploaded image, image url will be here
string
string
Max dimensions for the job
string
string
Max weight for the job
string
string
string
Actual dimensions for the job, as provided by customer
package.dimensions
Actual weight for the job, as provided by customer
package.weight
package.descriptionFromCustomer
Customers description of the parcel
package.totalDerveries
number
package.totalReturns
Total number of deliveries on the shipping point
number
price
payment
Price
Total number of returns on the shipping point
billing.address
Payment
billing.contact
Object with price details
Address
hero
messageToHero
Contact
Payment method used for the job
couponCode
Hero
createdAt
Billing address used to create invoice. If not supplied, then pickup address will be used instead
string
delivery
informShippingContact
string
Billing contact used to create invoice. If not supplied, then pickup contact will be used instead.
closing.reason
Date
closing.description
Information about Hero assigned to the Job
DeliveryInfo
Customers message to hero.
Coupon code used when job is created
boolean
Timestamp when job is created
Information about delivery
string
When set to true, specific SMS will go to the shipping contact phone number (if defined) when package is picked up.
Property is filled in only when job is in status CLOSED.
If property closing.reason is OTHER, then in this field will be written explanation why job was closed.
string
Reason why job was closed.
Property is filled in only when job is in status CLOSED. Possible values are: FAILED_PICKUP, FAILED_DELIVERY, LATE_CANCELLATION,
OTHER

Methods

Products/Quotas

To get products and quota information available for certain pickup address, destination address and productType (s, m, l, overweight) you will be calling Products api

Method: POST
URL: /api/v2.6/product

Request parameters

Property
Type
Required
Description
destination
Address
yes
Internal information if delivery is done via Hubs or directly
pickup
string
yes
Internal information if delivery is done via Hubs or directly
productType
Address
yes
Internal information if delivery is done via Hubs or directly
couponCode
string
no
Internal information if delivery is done via Hubs or directly
components
PriceComponent[]
no
Internal information if delivery is done via Hubs or directly
service
string
no
Internal information if delivery is done via Hubs or directly
totalDeliveries
number
no
Internal information if delivery is done via Hubs or directly
totalPickups
delivery.estimatedTime.from
no
Internal information if delivery is done via Hubs or directly
number
delivery.estimatedTime.to
no
Internal information if delivery is done via Hubs or directly
datetime
datetime
no
Internal information if delivery is done via Hubs or directly

Request properties

Response body contains list of Product entities.

Request Example

{
 "destination": {
   "postalCode": "80805",
   "city": "München",
   "countryCode": "DE",
   "geolocation": {
     "lat": 48.1703358,
     "lng": 11.587664399999994
   },
   "street": "Berliner Straße",
   "streetNo": "1",
   "addressLine2": ""
 },
 "pickup": {
   "postalCode": "80634",
   "city": "München",
   "countryCode": "DE",
   "geolocation": {
     "lat": 48.1464,
     "lng": 11.529089999999997
   },
   "street": "Arnulfstraße",
   "streetNo": "123",
   "addressLine2": "",
   "timeframe": {
     "to": null,
     "from": null,
     "pickupDate": "ASAP"
   }
 },
 "productType": "s",
 "productSize": {
   "dimensions": {
     "length": 10,
     "width": 10,
     "height": 10
   },
   "weight": 1
 },
 "components": []
}

Response Example

[
 {
   "id": "59159a3f609ce655746317f0",
   "type": "s",
   "deliveryDelay": {
     "from": 2,
     "to": 2,
     "precision": "hours",
     "estimate": {
       "from": null,
       "to": "2017-09-05T10:23:12.795Z",
       "precision": "hours"
     }
   },
   "dimensions": {
     "length": 10,
     "width": 10,
     "height": 10
   },
   "maxDimensions": {
     "length": 50,
     "width": 30,
     "height": 20
   },
   "weight": 1,
   "maxWeight": 5,
   "price": {
     "total": 11.67,
     "totalExcludingVat": 9.81,
     "vat": 1.86,
     "vatMultiplier": 1.19,
     "vatRate": "19%",
     "components": [
       {
         "type": "CITY-NOW",
         "label": "CITY-NOW",
         "price": 11.67,
         "mandatory": true,
         "applied": true
       }
     ]
   },
   "service": "CITY-NOW",
   "serviceVariant": 0
 },
 {
   "id": "59159a3f609ce65574631802",
   "type": "s",
   "deliveryDelay": {
     "from": 2,
     "to": 2,
     "precision": "days",
     "estimate": {
       "from": null,
       "to": "2017-09-07T21:59:59.999Z",
       "precision": "days"
     }
   },
   "latestPickupTime": "2017-09-05T16:00:00.000Z",
   "earliestPickupTime": "2017-09-05T08:23:07.861Z",
   "dimensions": {
     "length": 10,
     "width": 10,
     "height": 10
   },
   "maxDimensions": {
     "length": 50,
     "width": 30,
     "height": 20
   },
   "weight": 1,
   "maxWeight": 5,
   "price": {
     "total": 16.6,
     "totalExcludingVat": 13.95,
     "vat": 2.65,
     "vatMultiplier": 1.19,
     "vatRate": "19%",
     "components": [
       {
         "type": "EASY-ECONOMY",
         "label": "EASY-ECONOMY",
         "price": 16.6,
         "mandatory": true,
         "applied": true
       }
     ]
   },
   "service": "EASY-ECONOMY",
   "serviceVariant": 0
 }
]

Pickup Timeframes

To get list of available pickup timeframes for a certain date, you’ll call following API:

Method: GET
URL: /api/v2.6/pickup-timeframes?requestedDate=2017-01-13T015:56:12Z02:00

Request parameters

Property
Type
Required
Description
requestedDate
Date
yes
Web date format which should include timezone information.
offset
no
For how many next days to get timeframes. Default is 1.
integer

Response parameters

Property
Type
Description
frames
PickupTimeframe[]
Web date format which should include timezone information.

Response Example

[
 {
   "pickupDate": "2017-09-05T07:34:57.282Z",
   "frames": [
     {
       "pickupDate": "ASAP",
       "from": null,
       "to": null
     },
     {
       "pickupDate": "2017-09-05T10:00:00.000Z",
       "from": "2017-09-05T08:00:00.000Z",
       "to": "2017-09-05T10:00:00.000Z"
     },
     {
       "pickupDate": "2017-09-05T12:00:00.000Z",
       "from": "2017-09-05T10:00:00.000Z",
       "to": "2017-09-05T12:00:00.000Z"
     },
     {
       "pickupDate": "2017-09-05T14:00:00.000Z",
       "from": "2017-09-05T12:00:00.000Z",
       "to": "2017-09-05T14:00:00.000Z"
     },
     {
       "pickupDate": "2017-09-05T16:00:00.000Z",
       "from": "2017-09-05T14:00:00.000Z",
       "to": "2017-09-05T16:00:00.000Z"
     },
     {
       "pickupDate": "2017-09-05T18:00:00.000Z",
       "from": "2017-09-05T16:00:00.000Z",
       "to": "2017-09-05T18:00:00.000Z"
     }
   ]
 },
 {
   "pickupDate": "2017-09-06T07:34:57.282Z",
   "frames": [
     {
       "pickupDate": "2017-09-06T07:00:00.000Z",
       "from": "2017-09-06T06:00:00.000Z",
       "to": "2017-09-06T07:00:00.000Z"
     },
     {
       "pickupDate": "2017-09-06T09:00:00.000Z",
       "from": "2017-09-06T07:00:00.000Z",
       "to": "2017-09-06T09:00:00.000Z"
     },
     {
       "pickupDate": "2017-09-06T11:00:00.000Z",
       "from": "2017-09-06T09:00:00.000Z",
       "to": "2017-09-06T11:00:00.000Z"
     },
     {
       "pickupDate": "2017-09-06T13:00:00.000Z",
       "from": "2017-09-06T11:00:00.000Z",
       "to": "2017-09-06T13:00:00.000Z"
     },
     {
       "pickupDate": "2017-09-06T15:00:00.000Z",
       "from": "2017-09-06T13:00:00.000Z",
       "to": "2017-09-06T15:00:00.000Z"
     },
     {
       "pickupDate": "2017-09-06T17:00:00.000Z",
       "from": "2017-09-06T15:00:00.000Z",
       "to": "2017-09-06T17:00:00.000Z"
     },
     {
       "pickupDate": "2017-09-06T18:00:00.000Z",
       "from": "2017-09-06T17:00:00.000Z",
       "to": "2017-09-06T18:00:00.000Z"
     }
   ]
 },
 {
   "pickupDate": "2017-09-07T07:34:57.282Z",
   "frames": [
     {
       "pickupDate": "2017-09-07T07:00:00.000Z",
       "from": "2017-09-07T06:00:00.000Z",
       "to": "2017-09-07T07:00:00.000Z"
     },
     {
       "pickupDate": "2017-09-07T09:00:00.000Z",
       "from": "2017-09-07T07:00:00.000Z",
       "to": "2017-09-07T09:00:00.000Z"
     },
     {
       "pickupDate": "2017-09-07T11:00:00.000Z",
       "from": "2017-09-07T09:00:00.000Z",
       "to": "2017-09-07T11:00:00.000Z"
     },
     {
       "pickupDate": "2017-09-07T13:00:00.000Z",
       "from": "2017-09-07T11:00:00.000Z",
       "to": "2017-09-07T13:00:00.000Z"
     },
     {
       "pickupDate": "2017-09-07T15:00:00.000Z",
       "from": "2017-09-07T13:00:00.000Z",
       "to": "2017-09-07T15:00:00.000Z"
     },
     {
       "pickupDate": "2017-09-07T17:00:00.000Z",
       "from": "2017-09-07T15:00:00.000Z",
       "to": "2017-09-07T17:00:00.000Z"
     },
     {
       "pickupDate": "2017-09-07T18:00:00.000Z",
       "from": "2017-09-07T17:00:00.000Z",
       "to": "2017-09-07T18:00:00.000Z"
     }
   ]
 },
 {
   "pickupDate": "2017-09-08T07:34:57.282Z",
   "frames": [
     {
       "pickupDate": "2017-09-08T07:00:00.000Z",
       "from": "2017-09-08T06:00:00.000Z",
       "to": "2017-09-08T07:00:00.000Z"
     },
     {
       "pickupDate": "2017-09-08T09:00:00.000Z",
       "from": "2017-09-08T07:00:00.000Z",
       "to": "2017-09-08T09:00:00.000Z"
     },
     {
       "pickupDate": "2017-09-08T11:00:00.000Z",
       "from": "2017-09-08T09:00:00.000Z",
       "to": "2017-09-08T11:00:00.000Z"
     },
     {
       "pickupDate": "2017-09-08T13:00:00.000Z",
       "from": "2017-09-08T11:00:00.000Z",
       "to": "2017-09-08T13:00:00.000Z"
     },
     {
       "pickupDate": "2017-09-08T15:00:00.000Z",
       "from": "2017-09-08T13:00:00.000Z",
       "to": "2017-09-08T15:00:00.000Z"
     },
     {
       "pickupDate": "2017-09-08T17:00:00.000Z",
       "from": "2017-09-08T15:00:00.000Z",
       "to": "2017-09-08T17:00:00.000Z"
     },
     {
       "pickupDate": "2017-09-08T18:00:00.000Z",
       "from": "2017-09-08T17:00:00.000Z",
       "to": "2017-09-08T18:00:00.000Z"
     }
   ]
 }
]

Creating Jobs

To get list of available pickup timeframes for a certain date, you’ll call following API:

Method: GET
URL: /api/v2.6/pickup-timeframes?requestedDate=2017-01-13T015:56:12Z02:00

Request parameters

Property
Type
required
Description
pickup.address
Address
yes
pickup.contact
DateTime
yes
pickup.date
Contact
yes
pickup.timeframe
Normally should be copied from pickupDate proprety from one of the timeframes returned by calling GET /pickup-timeframes. Also accepts string value ‘ASAP’. ‘ASAP’ means Hero will come to pick up parcel within 1 hour after accepting request.
PickupTimeframe
yes
destination.address
Normally should be copied from one of the timeframes returned by calling GET /pickup-timeframes.
Address
yes
destination.contact
Contact
package.type
yes
string
package.descriptionFromCustomer
package.totalDeliveries
s, m, l, oversized
yes
string
package.totalPickups
Customers description of the parcel.
yes
price.components
yes
number
payment
billing.address
number
billing.contact
yes
messageToHero
PriceComponent[]
no
Total number of deliveries on shipping address
Payment
Address
no
no
Contact
Total number of pickups on shipping address
string
no
string
string
Indicates how customer wants to pay for a job.
no
boolean
no
service
no
externalReference
informShippingContact
no
delivery.estimatedTime.from
datetime
Message customer wants to be passed to Hero who is coming to pickup the parcel.
delivery.estimatedTime.to
no
datetime
no
If supplied system will try to create job using service requested. If not supplied, system will default to ‘CITY-NOW’ (codename: same_day_delivery)
if pickup/destination is within same city and it will default to ‘EASY-ECONOMY’ (codename: standard_shipping) if job pickup and address are not within same city.
Any text data clients want to connect to the job being created.
Default is false. When true is sent, specific email will go to shipping contact phone number when parcel is picked upAddress
Date time of requested latest delivery
Date time of requested earliest delivery

Response Parameters

Job entity.

Request Example

{
 "pickup": {
   "address": {
     "postalCode": "10969",
     "city": "Berlin",
     "countryCode": "DE",
     "geolocation": {
       "lat": 52.5072188,
       "lng": 13.3907193
     },
     "street": "Friedrichstraße",
     "streetNo": "44",
     "addressLine2": "additional info"
   },
   "contact": {
     "name": "Friedrich Niche",
     "company": "Mercedes",
     "phone": "+4915730080312"
   },
   "date": "2016-12-23T10:57:53.306Z",
   "timeframe": {
     "pickupDate": "2016-12-23T10:57:53.306Z",
     "from": "2016-12-23T11:00:00.000Z",
     "to": "2016-12-23T13:00:00.000Z"
   }
 },
 "destination": {
   "address": {
     "postalCode": "10969",
     "city": "Berlin",
     "countryCode": "RS",
     "geolocation": {
       "lat": 52.5072188,
       "lng": 13.3907193
     },
     "street": "Friedrichstraße",
     "streetNo": "44",
     "addressLine2": "additional info"
   },
   "contact": {
     "name": "Friedrich Niche",
     "company": "Mercedes",
     "phone": "+4915730080312"
   }
 },
 "package": {
   "type": "s",
   "descriptionFromCustomer": "items"
 },
 "messageToHero": "Please, be quiet",
 "couponCode": "MILAN1",
 "payment": {
   "type": "account"
 },
 "billing": {
   "address": {
     "postalCode": "10969",
     "city": "Berlin",
     "countryCode": "DE",
     "geolocation": {
       "lat": 52.5072188,
       "lng": 13.3907193
     },
     "street": "Friedrichstraße",
     "streetNo": "44",
     "addressLine2": "additional info"
   },
   "contact": {
     "name": "Friedrich Niche",
     "company": "Mercedes",
     "phone": "+4915730080312"
   }
 },
 "price": {
   "components": []
 },
 "externalReference":"this is test reference"
}

Response Example

{
"id": "584e67824339618c2197211d",
"billing": {
  "contact": {
    "name": "Mitar Milanovic",
    "companyName": "Codebehind",
    "vat": "111"
  },
  "address": {
    "street": "Mis Irbijeve 49",
    "streetNo": null,
    "postalCode": "11050",
    "city": "Belgrade",
    "countryCode": "RS",
    "countryName": null,
    "addressLine2": null
  }
},
"couponCode": "MILAN1",
"delivery": {
  "by": "HUB",
  "estimatedTime": {
    "date": "2016-12-19T16:00:00.000Z",
    "delay": 0,
    "precision": "days"
  }
},
"destination": {
  "address": {
    "street": "France",
    "streetNo": "2",
    "city": "Gaja-et-Villedieu",
    "countryCode": "FR",
    "countryName": null,
    "geolocation": {
      "lat": 43.0794485,
      "lng": 2.175196700000015
    },
    "postalCode": "11300",
    "addressLine2": "shipping address line 2"
  },
  "contact": {
    "companyName": "Shipping company",
    "name": "Shipping con name",
    "phone": "+381637054855"
  }
},
"hero": null,
"heroDistance": 7.12,
"messageToHero": "poruka heroju",
"invoice": null,
"offerId": null,
"package": {
  "type": "s",
  "descriptionFromCustomer": "items",
  "size": {}
},
"payment": {
  "type": "account"
},
"pickup": {
  "address": {
    "street": "Friedrichstraße",
    "streetNo": "245",
    "city": "Berlin",
    "countryCode": "DE",
    "countryName": null,
    "geolocation": {
      "lat": 52.50072,
      "lng": 13.390989999999988
    },
    "postalCode": "10969",
    "addressLine2": "address line 2"
  },
  "contact": {
    "companyName": "Pickup kompanija",
    "name": "Mitar Milanovic",
    "phone": "+381637054814"
  },
  "date": "2016-12-15T16:00:00.000Z",
  "timeframe": {
    "to": "2016-12-15T16:00:00.000Z",
    "from": "2016-12-15T14:00:00.000Z",
    "pickupDate": "2016-12-15T16:00:00.000Z"
  }
},
"price": {
  "total": 16.99,
  "totalExcludingVat": 14.28,
  "vat": 2.71,
  "vatMultiplier": 1.19,
  "vatRate": "19%",
  "components": [
    {
      "type": "packaging_price",
      "label": "packaging_price",
      "price": 2,
      "mandatory": false,
      "applied": true
    },
    {
      "type": "pickup_price",
      "label": "pickup_price",
      "price": 3,
      "mandatory": true,
      "applied": true
    },
    {
      "type": "gift_wrap",
      "label": "gift_wrap",
      "price": 3.99,
      "mandatory": false,
      "applied": false
    },
    {
      "type": "standard_shipping",
      "label": "standard_shipping",
      "price": 16.99,
      "mandatory": true,
      "applied": true
    },
    {
      "type": "discount",
      "label": "discount",
      "price": -5,
      "mandatory": true,
      "applied": true
    }
  ]
},
"status": "PENDING",
"userId": "56f5458eb22eaa5559f426a3"
}

Getting Jobs

To retrieve single job information use

Method: GET
URL: /api/v2.6/job/{id}

To retrieve all jobs created use. (No paging available ATM)

Method: GET
URL: /api/v2.6/job

Cancelling Jobs

Cancels the job. If executed successfully, job status will change to CANCELLED.

Method: POST
URL: /api/v2.6/job/{id}/cancel

Webhooks

To retrieve single job information use

Method: GET
URL: /api/v2.6/job/{id}

To retrieve all jobs created use. (No paging available ATM)

Method: GET
URL: /api/v2.6/job

Job Status Change

Method: POST
Payload:

{
   "jobId":"job unique identifier",
   "reference":"job external reference (if passed when job was created)",
   "oldStatus":"old job status",
   "newStatus":"new job status",
   "trackingLink": "job tracking link (if applicable)"
};

Job Statuses

Name
Description
INCOMING
Request is confirmed and waiting for processing.
DISPATCHED
Job is dispatched to heroes.
CANCELLED
Customer cancelled job request.
DECLINED
System denied job request.
ASSIGNED
Hero is assigned to pickup the parcel.
ONTHEWAY
Hero is on the way to pickup parcel.
PICKEDUP
Hero picked up parcel from customer.
DROPPEDOFF
Hero dropped off parcel at the hub.
PREPARINGSHIPMENT
Hub operators accepted the parcel at the hub.
SHIPPED
Operators created shipments using partner services.
COMPLETE
Parcel has arrived to final destination.
CLOSED
Job is closed.