Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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.

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
titleOn this page

Table of Contents
minLevel2
 


The DispatchOrder resource has the following attributes:

AttributeType

Description

hrefstring

URI to the resource.

idstring

Collection order ID. Read-only.

statusstring

Collection order status.

created_atTime

Collection order creation time.

addressObject

Address which the collection is to be made from.

shipmentsArray[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.

commentstring

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
titleNote! 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

ParameterType

Description

Validation

dispatch_point_idinteger

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

shipmentsArray

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.         

commentstring

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.

addressAddressForm

Collection order address

The attribute is not required.

It is required when the dispatch_point_id attribute is not provided

office_hoursstring

Point working hours

The attribute is not required.

Determines the point's working hours, if we create a collection order for an address.

namestringPoint name. Used to create a dispatch point.The attribute is not required.
phonestringTelephone contact. Used to create dispatch_point.The attribute is not required.
emailstringE-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 https://confluence.inpost.pl/display/SHIPX/%5B1.3%5D+Obiekt+Addressattribute 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.