[1.23.0] Dispatch Orders

 

Warning!

Resource available only for specific countries: PL

DispatchOrders allow ordering courier to collect shipments from the client.

Each DispatchOrder has status, which describing it's state. Available statuses:

  • new - new order, which is not yet passed to execution

  • sent - order is passed to execution, but is not yet accepted


Structure

DispatchOrder resource has the following attributes:

Attribute

Type

Description

Availability

Attribute

Type

Description

Availability

id

String

ID number (read-only)

PL

status

String

Order status

PL

created_at

DateTime

Timestamp describing when order was created

PL

address

Address

Address, where courier will take over shipments

PL

shipments

Array[Shipment]

Array of shipments that will be taken by the courier. Required Shipment attributes:

  • href - shipment's url address

  • id - shipment's id

  • tracking_number - shipment's tracking number

PL

comment 

String

Optional comments for the DispatchOrder

PL

Example of DispatchOrder resource in JSON format:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 { "href": "https://api-shipx-pl.easypack24.net/v1/dispatch_orders/1", "id": 1, "status": "sent", "address": { "id": "123", "street": "Tottenham Court Road", "building_number": "14", "post_code": "W1T 1JY", "city": "London", "country_code": "GB" }, "shipments": [ { "href": "https://api-shipx-pl.easypack24.net/v1/shipments/8", "id": 8, "tracking_number": "622111081631876319900026" } ], "comments": [ { "24",  "comment": "Some Test Comment", "created_at": "2018-02-14T11:37:07.852+01:00" } ], "created_at": "2018-02-14T11:37:07.843+01:00", "updated_at": "2018-02-14T11:37:08.340+01:00" }

 

Authorization

Resource require providing correct access token.


 

Creating new DispatchOrder

 

DispatchOrder for specific address

Generating of DispatchOrder require providing correct address using address attribute.

Using data from address, algorithm is calculating checksum, so it is very important to provide correct address without typos etc.

Later, this checksum is used to determine if this DispatchPoint is already registered in our database. If not, a new DispatchPoint is generated (only for locker's shipments).

Next, DispatchPoint found or generated this way is assigned to DispatchOrder for the courier, allowing order execution.

 

Warning! Debit clients

We are not showing prices after creation of DispatchOrder, for debit clients.

price attribute will be returned as null.



1 POST /v1/organizations/:organization_id/dispatch_orders

Available parameters:

Parameter

Type

Description

Validation

Availability

Parameter

Type

Description

Validation

Availability

dispatch_point_id

Integer

Id of DispatchPoint for the place, from where shipment should be taken by the courier.
The address of this DispatchPoint will be assigned to DispatchOrder as a pick-up point.

In general, this attribute is not required.

It is starting to be required, only when address attribute is not provided.



PL

shipments

Array

List of shipments ids, for which DispatchOrder is being generated.

 

 

Attribute is required.

  • Shipments must be in confirmed status and can't be assigned to any other DispatchOrder

  • All shipments must belong to the same carrier type.

  • There is no option to join allegro and non-allegro shipments in the same DispatchOrder

  • Allegro services can be joined together

  • Non-allegro services can be joined together

PL

comment

String

Optional comment

The attribute is not required for creating DispatchOrder.

But is required when DispatchOrder is updated.

PL

address

Address

Address of pick-up point (DispatchPoint)

Attribute is required.

PL

office_hours

String

Describing time when DispatchPoint is available for picking up shipments.

Attribute is not required.

PL

name 

String

Name used for generating new DispatchPoint in our database.

Attribute is required.

PL

phone

String

Phone number used for generating DispatchPoint.

Attribute is required.

PL

email 

String

Email address used for generating DispatchPoint.

Attribute is not required.

PL

Example request:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 curl -X POST https://api-shipx-pl.easypack24.net/v1/organizations/1/dispatch_orders -H 'Authorization: Bearer token' -H 'Content-Type: application/json' -d '{ "shipments": ["1", "2"], "comment": "Dowolny komentarz do zlecenia odbioru", "name": "Przykładowa nazwa DispatchPoint", "phone": "505404202", "email": "sample@email.com", "address": { "street": "Malborska", "building_number": "130", "city": "Krakow", "post_code": "31-209", "country_code": "PL" } }'

Example response

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 HTTP/1.1 201 Created Content-Type: application/json { "href": "https://api-shipx-pl.easypack24.net/v1/dispatch_orders/1", "id": 1, "status": "sent", "address": { "id": "123", "street": "Malborska", "building_number": "130", "post_code": "30-624", "city": "Kraków", "country_code": "PL", }, "shipments": [ { "href": "https://api-shipx-pl.easypack24.net/v1/shipments/8", "id": 8, "tracking_number": "622111081631876319900026" } ], "comments": [ { "id": 24, "comment": "Dowolny komentarz do zlecenia odbioru", "created_at": "2018-02-14T11:37:07.852+01:00" } ], "created_at": "2018-02-14T11:37:07.843+01:00", "updated_at": "2018-02-14T11:37:08.340+01:00" }

 

Possible Errors

  • validation_failed - provided data are incorrect, e.g DispatchPoint not exist or one of shipments is in incorrect status

  • invalid_range - invalid shipment id, e.g range of the id is not matching Integer type

  • dispatch_point_and_address_cannot_be_mixed - address and dispatch_point_id can't be provided at the same time 


 

DispatchOrders list


DispatchOrders list for specific organization can be accessed by using this endpoint:

1 GET /v1/organizations/:organization_id/dispatch_orders

Example request:

1 curl -X GET https://api-shipx-pl.easypack24.net/v1/organizations/1/dispatch_orders -H 'Authorization: Bearer token' -H 'Content-Type: application/json'

Example response:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 HTTP/1.1 200 OK Content-Type: application/json  { "href": "https://api-shipx-pl.easypack24.net/v1/organizations/1/dispatch_orders", "count": 15, "per_page": 30, "page": 1, "created_at": "2016-03-21T10:13:58.625+01:00", "items": [ { "href": "https://api-shipx-pl.easypack24.net/v1/dispatch_orders/3", "id": 123, ... other attribute omitted for brevity .... } ... other items omitted for brevity ... ] }

 

Possible Errors:

  • resource_not_found - organization with this ID not exist

  • forbidden - this is not valid token for this organization


 

DispatchOrder details

1 GET /v1/dispatch_orders/:id

Example request

1 curl -X GET https://api-shipx-pl.easypack24.net/v1/dispatch_orders/1 -H 'Authorization: Bearer token' -H 'Content-Type: application/json'

Example response

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 HTTP/1.1 200 OK Content-Type: application/json { "href": "https://api-shipx-pl.easypack24.net/v1/dispatch_orders/1", "id": 1, "status": "sent", "address": { "id": "123", "street": "Tottenham Court Road", "building_number": "14", "post_code": "W1T 1JY", "city": "London", "country_code": "GB" }, "shipments": [ { "href": "https://api-shipx-pl.easypack24.net/v1/shipments/8", "id": 8, "tracking_number": "622111081631876319900026" } ], "comments": [ { "id": 24,  "comment": "Example of DispatchOrder comment", "created_at": "2018-02-14T11:37:07.852+01:00" } ], "created_at": "2018-02-14T11:37:07.843+01:00", "updated_at": "2018-02-14T11:37:08.340+01:00" }

 

Possible Errors

  • resource_not_found - when DispatchOrder with this id not exist


 

Deleting Dispatch Orders

Dispatch order Can be deleted in the following statuses only: new, sent 

1 DELETE /v1/dispatch_orders/:id

Example request

1 curl -X DELETE https://api-shipx-pl.easypack24.net/v1/dispatch_orders/1 -H 'Authorization: Bearer token' -H 'Content-Type: application/json'

Response

1 2 HTTP/1.1 204 No Content Content-Type: application/json

 

Error information

  • resource_not_found - Dispatch Order with the given ID cannot be found,

  • invalid_status - In case when the Dispatch Order is in a status other than new or sent 


 

Creating Dispatch Order comment

When creating a dispatch order, we allow adding additional comments.

Additionally, we allow creating a comment for an already existing Dispatch Order. 

1 POST /v1/organizations/:organization_id/dispatch_orders/:dispatch_order_id/comment

Request example

1 2 3 curl -X POST https://api-shipx-pl.easypack24.net//v1/organizations/1/dispatch_orders/1/comment -H 'Authorization: Bearer token' -H 'Content-Type: application/json' -d '{ "comment": "Dodatkowy dowolny komentarz do zlecenia odbioru" }'

Response

1 2 3 4 5 6 7 8 9 HTTP/1.1 201 Created Content-Type: application/json   { "id": 37, "href": "https://api-shipx-pl.easypack24.net/v1/organizations/1/dispatch_orders/17/comment", "comment": "Dodatkowy dowolny komentarz do zlecenia odbioru", "created_at": "2018-02-15T10:32:31.345+01:00" }

 

Editing Dispatch Order comments

When creating a dispatch order, we allow adding additional comments.

Additionally, we allow editing a comment for an already existing Dispatch Order. 

1 PUT /v1/organizations/:organization_id/dispatch_orders/:dispatch_order_id/comment

Request example

1 2 3 4 curl -X PUT https://api-shipx-pl.easypack24.net/v1/organizations/1/dispatch_orders/1/comment -H 'Authorization: Bearer token' -H 'Content-Type: application/json' -d '{ "id": 37, "comment": "Aktualizacja komentarza" }

Response

1 2 3 4 5 6 7 8 HTTP/1.1 201 Created Content-Type: application/json { "id": 37, "href": "https://api-shipx-pl.easypack24.net/v1/organizations/1/dispatch_orders/17/comment", "comment": "Aktualizacja komentarza", "created_at": "2018-02-15T10:32:31.345+01:00" }

 

Error information

  • resource_not_found - Dispatch Order with the given ID cannot be found or Organization with the given ID cannot be found.

  • forbidden - Token does not allow for editing Dispatch Order comments for the given organization.


 

Deleting Dispatch Order comment

We allow deleting a comment for an already existing Dispatch Order.

1 DELETE /v1/organizations/:organization_id/dispatch_orders/:dispatch_order_id/comment

Request example

1 curl -X DELETE https://api-shipx-pl.easypack24.net/v1/organizations/1/dispatch_orders/1/comment -H 'Authorization: Bearer token' -H 'Content-Type: application/json'

Response

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 HTTP/1.1 201 Created Content-Type: application/json   {     "href": "https://api-shipx-pl.easypack24.net/v1/dispatch_orders/2",     "id": 2,     "status": "sent",     "external_id": 2000000001,     "price": null,     "address": {         "id": 211,         "street": "Malborska",         "building_number": "130",         "line1": null,         "line2": null,         "city": "Krakow",         "post_code": "31-209",         "country_code": "PL"     },     "statuses": [],     "shipments": [         {             "href": "https://api-shipx-pl.easypack24.net/v1/shipments/103",             "id": 103,             "tracking_number": "520000017830390003050784"         }     ],     "comments": [         {             "id": 24,             "comment": "Test 22",             "created_at": "2018-05-15T11:34:54.119+02:00"         },         {             "id": 23,             "comment": "Test 21",             "created_at": "2018-05-15T11:34:51.438+02:00"         },         {             "id": 22,             "comment": "Test 20",             "created_at": "2018-05-15T11:34:48.637+02:00"         }     ],     "created_at": "2018-05-15T09:19:32.317+02:00",     "updated_at": "2018-05-15T09:19:32.448+02:00" }