Dispatch Order
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 executionsent
- order is passed to execution, but is not yet accepted
Structure
DispatchOrder
resource has the following attributes:
Attribute | Type | Description |
---|---|---|
| String | ID number (read-only) |
| String | Order status |
| DateTime | Timestamp describing when order was created |
| Address | Address, where courier will take over shipments |
| Array[Shipment] | Array of shipments that will be taken by the courier. Required
|
| String | Optional comments for the DispatchOrder |
Example of DispatchOrder
resource in JSON format:
{
"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"
}
Creating new DispatchOrder
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.
Asynchronous operation, to get the order number use Dispatch Order | DispatchOrder details, the order number is in the "external_id" parameter.
Warning! Debit clients
We are not showing prices after creation of DispatchOrder, for debit clients.
price
attribute will be returned as null.
POST /v1/organizations/:organization_id/dispatch_orders
Available parameters:
Parameter | Type | Description | Validation |
---|---|---|---|
| Array | List of shipments ids, for which DispatchOrder is being generated.
| Attribute is required.
|
| String | Optional comment | The attribute is not required for creating DispatchOrder. But is required when DispatchOrder is updated. |
| Address | Address of pick-up point (DispatchPoint) | Attribute is required. |
| String | Describing time when DispatchPoint is available for picking up shipments. | Attribute is not required. |
| String | Name used for generating new DispatchPoint in our database. | Attribute is required. |
| String | Phone number used for generating DispatchPoint. | Attribute is required. |
| String | Email address used for generating DispatchPoint. | Attribute is not required. |
Example request:
curl -X POST 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": "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"
}
}'
Example 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"
}
Possible Errors
validation_failed
- provided data are incorrect, e.g DispatchPoint not exist or one of shipments is in incorrect statusinvalid_range
- invalid shipment id, e.g range of the id is not matching Integer typedispatch_point_and_address_cannot_be_mixed
-address
anddispatch_point_id
can't be provided at the same timealready_dispatched
- means that an order has been created for at least one shipment indicated in the requestvarious_types_of_carrie
- means that at least one shipment is of a different service category. These must be shipments created using the InPost parcel lockers services or only using the InPost Courier services.
DispatchOrders list
DispatchOrders list for specific organization can be accessed by using this endpoint:
GET /v1/organizations/:organization_id/dispatch_orders
Example request:
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:
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 existforbidden
- this is not valid token for this organization
DispatchOrder details
GET /v1/dispatch_orders/:id
Example request
curl -X GET https://api-shipx-pl.easypack24.net/v1/dispatch_orders/1 -H 'Authorization: Bearer token' -H 'Content-Type: application/json'
Example response
HTTP/1.1 200 OK
Content-Type: application/json
{
"href": "https://api-shipx-pl.easypack24.net/v1/dispatch_orders/3223738",
"id": 3223738,
"status": "sent",
"external_id": 2003222292,
"price": null,
"address": {
"id": 1192036131,
"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/793374228",
"id": 793374228,
"tracking_number": "602677358231630337744964"
}
],
"comments": [
{
"id": 3198262,
"comment": "Dowolny komentarz do zlecenia odbioru",
"created_at": "2022-05-27T10:15:31.765+02:00"
}
],
"created_at": "2022-05-27T10:15:31.756+02:00",
"updated_at": "2022-05-27T10:15:32.122+02:00"
}
Possible Errors
resource_not_found
- when DispatchOrder with this id not exist
Deleting Dispatch Orders
Dispatch order Can be deleted in the following statuses only: new, sent
DELETE /v1/dispatch_orders/:id
Example request
curl -X DELETE https://api-shipx-pl.easypack24.net/v1/dispatch_orders/1 -H 'Authorization: Bearer token' -H 'Content-Type: application/json'
Response
HTTP/1.1 204 No Content
Content-Type: application/json
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 thannew
orsent
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.
POST /v1/organizations/:organization_id/dispatch_orders/:dispatch_order_id/comment
Request example
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
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.
PUT /v1/organizations/:organization_id/dispatch_orders/:dispatch_order_id/comment
Request example
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
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"
}
Error information
resource_not_found
- Dispatch Order with the given ID cannot be found or Organization with the given ID cannot be found.forbidden
- Token does not allow for editing Dispatch Order comments for the given organization.
Deleting Dispatch Order comment
We allow deleting a comment for an already existing Dispatch Order.
DELETE /v1/organizations/:organization_id/dispatch_orders/:dispatch_order_id/comment
Request example
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
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"
}