Page Comparison

We allow additional comments to be provided for an existing collection order. In addition, we allow updates of a comment assigned to a particular collection order.

Sample request

Creating a collection order, we allow an optional comment to be provided.
In addition, we allow other comments to be added to an already existing collection order.

Collection orders allow for ordering a courier visit in order to collect an earlier prepared shipment.

Every collection order has a status which determines its condition. The statuses supported are:

• new - a new collection order which has not been transferred to processing yet,
• sent - the collection order has been transferred to processing, but has not been accepted yet,
• accepted - the order has been accepted for processing by the courier,
• done - the collection order has been completed,
• rejected - the collection order has been rejected by the courier,
• canceled - the order has been canceled,

Panel

bgColor	#f0f0f0
titleBGColor	#f0f0f0
title	On this page

Table of Contents

minLevel	2

The DispatchOrder resource has the following attributes:

Attribute	Type	Description
`href`	string	URI to the resource.
`id`	string	Collection order ID. Read-only.
`status`	string	Collection order status.
`created_at`	Time	Collection order creation time.
`address`	Object	Address which the collection is to be made from.
`shipments`	Array[Shipment]	Table of shipments the collection order applies to. The Shipment object contains the attributes: • href - shipment's URI address, • id - shipment's ID, • tracking_number - shipment's tracking number.
comment	string	Optional comment to the collection order

Sample DispatchOrder resource in the JSON format:

Code Block

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

Authentication

Access to the resource and its methods requires provision of the correct and valid access token.

Info

title	Note! Debit clients

After creating a collection order, we do not return prices for debit clients.
The price attribute takes the null value

Creating a new collection order

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

Parameters

Parameter	Type	Description	Validation
`dispatch_point_id`	integer	ID of the dispatch point which the shipment is to be collected from (the dispatch point address will become the collection order address).	The attribute is not required. It is required when the address attribute is not provided
`shipments`	Array	List of shipment IDs which the collection order is to be created for.	The attribute is required. • The parcels must be in the confirmed status and cannot be assigned to a different collection order in the new, sent, accepted or done status. • In addition, they must be parcels from the same carrier. • It is not possible to create one collection order for allegro and other shipments. • Shipments can be either for allegro, or any other.
`comment`	string	Optional comment to the collection order	The attribute is not required to create a collection order. It becomes required when creating a comment to an already existing collection order.
`address`	AddressForm	Collection order address	The attribute is not required. It is required when the dispatch_point_id attribute is not provided
office_hours	string	Point working hours	The attribute is not required. Determines the point's working hours, if we create a collection order for an address.
name	string	Point name. Used to create a dispatch point.	The attribute is not required.
phone	string	Telephone contact. Used to create dispatch_point.	The attribute is not required.
email	string	E-mail contact. Used to create dispatch_point.	The attribute is not required.

Sample request

Code Block

POST /v1/organizations/:org_id/dispatch_orders HTTP/1.1
Host: api-shipx-pl.easypack24.net
Content-Type: application/json
Authorization: Bearer lkfjasd9f70y43ohriw...[ommited for brevity]...
 
{
	"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"
    }
 }

Response

Code Block

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

Shipments collection order for address

Generation of an order for an address makes the address necessary to be provided by the address attribute Address object

The system generates the checksum from the information provided, attention has to be paid to ensure that the address is exact and without errors (the so-called typographic errors)

Based on the checksum, the system verifies whether a dispatch point with the same address exists in the database, if not, a new dispatch point is automatically generated (applies only to parcel station shipments).

The collection order (DispatchOrder) is executed to the newly generated dispatch point (DispachPoint).

Errors

• validation_failed - data sent by the user are incorrect, e.g. the stated dispatch point or any of the shipments has an incorrect status
• invalid_range - an incorrect shipment ID range has been provided, the range is not within the range of Integer values
• dispatch_point_and_address_cannot_be_mixed - It is not allowed to simultaneously assign collection orders for an address and a dispatch point id

Collecting information about a collection order

Code Block
GET /v1/dispatch_orders/:order_id

Sample request

Code Block
GET /v1/dispatch_orders/1 HTTP/1.1 Host: api-shipx-pl.easypack24.net Content-Type: application/json Authorization: Bearer lkfjasd9f70y43ohriw...[ommited for brevity]...

Response

Code Block

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

Errors

resource_not_found - in the event that the order with the stated ID is not found.

Removing a collection order

A collection order can only be deleted when it has new or sent status.

Code Block
DELETE /v1/dispatch_orders/1

Sample request

Code Block
DELETE /v1/dispatch_orders/1 HTTP/1.1 Host: api-shipx-pl.easypack24.net Content-Type: application/json Authorization: Bearer lkfjasd9f70y43ohriw...[ommited for brevity]...

Response

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

Errors

resource_not_found - in the event that the order with the stated ID is not found,
invalid_status - in the event that the order with the stated ID is in a different status than new or sent,

List of collection orders

The collection orders list within the given organization can be collected at:

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

Sample request

Code Block
GET /v1/organizations/12345/dispatch_orders HTTP/1.1 Host: api-shipx-pl.easypack24.net Content-Type: application/json Authorization: Bearer lkfjasd9f70y43ohriw...[ommited for brevity]...

In reply to a correctly sent request, the server will return a response with HTTP 200 OK code:

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

Errors that may occur when collecting the collection orders list:

resource_not_found - the organization which the user wants to collect the collection orders list for does not exist,
forbidden - the token does not authorize to collect the collection orders list for the selected organization..

Creating a comment to a collection order

Creating a collection order, we allow an optional comment to be provided.

In addition, we allow other comments to be added to an already existing collection order.

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

Sample request

Code Block

POST /v1/organizations/:organization_id/dispatch_orders/:dispatch_order_id/comment HTTP/1.1
Host: api-shipx-pl.easypack24.net
Content-Type: application/json
Authorization: Bearer lkfjasd9f70y43ohriw...[ommited for brevity]...
 
{
	"comment": "Dodatkowy dowolny komentarz do zlecenia odbioru"
}

In reply to a correctly sent request, the server will return a response with HTTP 201 Created code:

Code Block

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": "To jest jakis nastepny testowy komentarz",
    "created_at": "2018-02-15T10:32:31.345+01:00"
}

Updating a comment to a collection order

We allow additional comments to be provided for an existing collection order.

In addition, we allow updates of a comment assigned to a particular collection order.

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

Sample request

Code Block

PUT /v1/organizations/:organization_id/dispatch_orders/:dispatch_order_id/comment HTTP/1.1
Host: api-shipx-pl.easypack24.net
Content-Type: application/json
Authorization: Bearer lkfjasd9f70y43ohriw...[ommited for brevity]...
 
{
	"id": 37,
	"comment": "Aktualizacja komentarza"
}

In reply to a correctly sent request, the server will return a response with HTTP 201 Created code:

Code Block

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

Errors that may occur when collecting the collection orders list:

resource_not_found - the organization which the user wants to collect the collection orders list for does not exist,
forbidden - the token does not authorize to collect the collection orders list for the selected organization.

Delete comment to the dispatch order

For the existing dispatch order, we provide option of delete additional comments.

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

Request example

Code Block

DELETE /v1/organizations/:organization_id/dispatch_orders/:dispatch_order_id/comment HTTP/1.1
Host: api-shipx-pl.easypack24.net
Content-Type: application/json
Authorization: Bearer lkfjasd9f70y43ohriw...[ommited for brevity]...
 
{
	"comment_ids": [20,21]
}

In response to a request sent correctly, the server returns the response with code HTTP 200 OK:

Code Block

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

The errors that can occur while retrieving the list of receiving orders:

resource_not_found - organization for which the user wants to get a list of dispatch orders, does not exist,
forbidden - the token does not entitle the user to get the list of dispatch orders for the selected organization.

Versions Compared

Old Version 4

New Version 5

Key

Authentication

Creating a new collection order

Collecting information about a collection order

Removing a collection order

List of collection orders

Sample request

Creating a comment to a collection order

Sample request

Updating a comment to a collection order

Sample request

Delete comment to the dispatch order

Request example