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 | ||
---|---|---|
| ||
After creating a collection order, we do not return prices for debit clients. |
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. |
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" "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+Address
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
a collectionthe dispatch order
For an existing collection For the existing dispatch order, we allow a comment or their collection to be removed.Code Blockprovide option of delete additional comments.
Code Block |
---|
DELETE /v1/organizations/:organization_id/dispatch_orders/:dispatch_order_id/comment |
Sample request
Code BlockRequest 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 reply response to a request sent correctly sent request, the server will return a returns the response with code HTTP 200 Created codeOK:Code Block
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.