[1.23.0] Dispatch Orders

Warning!

Resource available only for specific countries: PL

DispatchOrders allow to order 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 is not yet accepted
accepted - order is accepted to execution by the courier
done - order is executed
rejected - order is rejected by the courier
canceled - order is canceled

On this page

Structure

DispatchOrder resource has following attributes:

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:

{
	"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 to provide correct access token.

DispatchOrders list

Listę zleceń odbioru w ramach określonej organizacji można pobrać pod adresem:
DispatchOrders list for specific organization can be accessed by using this endpoint:

GET /v1/organizations/:organization_id/dispatch_orders

Example request:

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:

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

GET /v1/dispatch_orders/:id

Example request

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

Example response

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

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, 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.

POST /v1/organizations/:organization_id/dispatch_orders

Available parameters:

Parameter	Type	Description	Validation	Availability
`dispatch_point_id`	Integer	Id of DispatchPoint for the place, from where shipment should be taken by the courier. 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	Attribute is not required for creating DispatchOrder. But is is required when DispatchOrder is updated.	PL
`address`	Address	Address of pick-up point (DispatchPoint)	In general this attribute is not required. It is starting to be required, only when `dispatch_point_id` attribute is not provided.	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 not required.	PL
phone	String	Phone number used for generating DispatchPoint.	Attribute is not required.	PL
`email`	String	Email address used for generating DispatchPoint.	Attribute is not required.	PL

Example request:

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": "Example of DispatchOrder comment",
	"name": "Example DispatchPoint name",
 	"phone": "505404202",
	"email": "sample@email.com",
	"address": { 
		"id": "123", 
		"street": "Tottenham Court Road", 
		"building_number": "14", 
		"post_code": "W1T 1JY", 
		"city": "London", 
		"country_code": "GB" 
	}
}'

Example response

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": "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

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 cant be provided at the same time

Deleting Dispatch Orders

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

DELETE /v1/dispatch_orders/:id

Example request

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

Response

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.

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

Request example

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

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.

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

Request example

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

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 Organisation with the given ID cannot be found.
forbidden - Token does not allow for editing Dispatch Order comments for the given organisation.

Deleting Dispatch Order comment

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

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

Request example

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

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"
}