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:
{ "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.
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
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 required. |
phone | string | Telephone contact. Used to create dispatch_point. | The attribute is not required. |
string | E-mail contact. Used to create dispatch_point. | The attribute is not required. |
Sample request
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
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
GET /v1/dispatch_orders/:order_id
Sample request
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
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.
DELETE /v1/dispatch_orders/1
Sample request
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
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:
GET /v1/organizations/:organization_id/dispatch_orders
Sample request
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:
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.
POST /v1/organizations/:organization_id/dispatch_orders/:dispatch_order_id/comment
Sample request
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:
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.
PUT /v1/organizations/:organization_id/dispatch_orders/:dispatch_order_id/comment
Sample request
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:
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.
DELETE /v1/organizations/:organization_id/dispatch_orders/:dispatch_order_id/comment
Request example
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:
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.