Page Comparison

Info

title	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

Panel

bgColor	#f0f0f0
titleBGColor	#f0f0f0
title	On this page

Table of Contents

minLevel	2

Structure

DispatchOrder resource has following attributes:

AttributeTypeDescriptionAvailabilityidStringID number (read-only)PLstatusStringOrder statusPLcreated_atDateTimeTimestamp describing when order was createdPLaddressAddressAddress, where courier will take over shipmentsPLshipmentsArray[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

PLcomment StringOptional comments for the DispatchOrderPL

Example of DispatchOrder resource in JSON format:

Code Block{ "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": [

Info

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

On this page

Table of Contents

Structure

DispatchOrder resource has the 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:

Code Block

language	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": [
        {
		 "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"
}

to provide

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:

Code Block
GET /v1/organizations/:organization_id/dispatch_orders

Example request:

Code Block
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:

Code Block

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

Code Block
GET /v1/dispatch_orders/:id

Example request

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

Example response

Code BlockHTTP/1.1 200 OK Content-Type: application/json { "href": "

Creating new DispatchOrder

Info

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.

Info

Warning! Debit clients

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

price attribute will be returned as null.

Code Block

language	json

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

Code Block

language	json

curl -X POST https://api-shipx-pl.easypack24.net/v1/organizations/1/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": [{ hrefhttps://api-shipx-pl.easypack24.net/v1/shipments/8 id: 8 trackingnumber622111081631876319900026} ], "comments": [ 24 commentExample of DispatchOrder comment "created_at"2018-02-14T11:37:07.852+01:00" } ], createdat2018-02-14T11:37:07.843+01:00 "updated_at2018-02-14T11:37:08.340+01:00" }

Possible Errors

resource_not_found - when DispatchOrder with this id not exist

Creating new DispatchOrder

Info

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

Info

title	Warning! Debit clients

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

price attribute will be returned as null.

Code Block
POST /v1/organizations/:organization_id/dispatch_orders

Available parameters:

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

PLshipmentsArray

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

PLcommentStringOptional comment

Attribute is not required for creating DispatchOrder.

But is is required when DispatchOrder is updated.

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

PLoffice_hoursStringDescribing time when DispatchPoint is available for picking up shipments.

Attribute is not required.

PLname StringName used for generating new DispatchPoint in our database.Attribute is not required.PLphoneStringPhone number used for generating DispatchPoint.Attribute is not required.PLemail StringEmail address used for generating DispatchPoint.Attribute is not required.PL

Example request:

Code Blockcurl -X POST

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

Warning

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:

Code Block

language	json

GET /v1/organizations/:organization_id/dispatch_orders

Example request:

Code Block

language	json

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:

Code Block

language	json

HTTP/1.1 200 OK
Content-Type: application/json
 {
	"href": "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" } }

",
	"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 ...
	]
}

Warning

Possible Errors:

resource_not_found - organization with this ID not exist
forbidden - this is not valid token for this organization

DispatchOrder details

Code Block

language	json

GET /v1/dispatch_orders/:id

Example request

Code Block

language	json

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

Example response

Code Block

language	json

HTTP/1.1

201Created

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,

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

Code Block

language	json

DELETE /v1/dispatch_orders/:id

Example request

Code Block

language	json

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

Response

Code Block

language	json

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

Warning

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.

Code Block

language	json

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

Request example

Code Block

language	json

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

Code Block

language	json

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.

Code Block

language	json

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

Request example

Code Block

language	json

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

Code Block

language	json

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

Warning

Error information

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

Organisation organisation

Deleting Dispatch Order comment

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

Code Block

language	json

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

Request example

Code Block

language	json

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

Code Block

language	json

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

Versions Compared

Old Version 3

New Version Current

Key

Structure

Structure

Authorization

DispatchOrders list

DispatchOrder details

Creating new DispatchOrder

DispatchOrder for specific address

Warning! Debit clients

Creating new DispatchOrder

DispatchOrders list

DispatchOrder details

Deleting Dispatch Orders

Creating Dispatch Order comment

Editing Dispatch Order comments

Deleting Dispatch Order comment