Page tree
Skip to end of metadata
Go to start of metadata

Warning!

Resource available only for specific countries: PL

DispatchOrders allow to order 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 execution
  • sent - order is passed to execution, but is is not yet accepted
  • accepted - order is accepted to execution by the courier
  • done - order is executed
  • rejected - order is rejected by the courier
  • canceled - order is canceled


On this page

 

Structure

DispatchOrder resource has following attributes:

AttributeTypeDescriptionAvailability
idStringID number (read-only)PL
statusStringOrder statusPL
created_atDateTimeTimestamp describing when order was createdPL
addressAddressAddress, where courier will take over shipmentsPL
shipmentsArray[Shipment]

Array of shipments that will be taken by the courier. Required Shipment attributes:

  • href - shipment's url address
  • id - shipment's id
  • tracking_number - shipment's tracking number
PL
comment StringOptional comments for the DispatchOrderPL

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



Authorization

Resource require to provide correct access token.


DispatchOrders list

Listę zleceń odbioru w ramach określonej organizacji można pobrać pod adresem:
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 exist
  • forbidden - 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/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": [
        {
		 "id": 24,
		 "comment": "Example of DispatchOrder 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"
}

Possible Errors

  • resource_not_found - when DispatchOrder with this id not exist



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, 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.

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:

ParameterTypeDescriptionValidationAvailability
dispatch_point_idIntegerId of DispatchPoint for the place, from where shipment should be taken by the courier.
Address of this DispatchPoint will be assigned to DispatchOrder as a pick-up point.

In general this attribute is not required.

It is starting to be required, only when address attribute is not provided.


PL
shipmentsArray

List of shipments ids, for which DispatchOrder is being generated.




Attribute is required.

  • Shipments must be in confirmed status and can't be assigned to any other DispatchOrder
  • All shipments must belong to the same carrier type.
  • There is no option to join allegro and non-allegro shipments in the same DispatchOrder
  • Allegro services can be joined together
  • Non-allegro services can be joined together
PL
commentStringOptional comment

Attribute is not required for creating DispatchOrder.

But is is required when DispatchOrder is updated.

PL
addressAddressAddress of pick-up point (DispatchPoint)

In general this attribute is not required.

It is starting to be required, only when dispatch_point_id attribute is not provided.

PL
office_hoursStringDescribing time when DispatchPoint is available for picking up shipments.

Attribute is not required.

PL
name StringName used for generating new DispatchPoint in our database.Attribute is not required.PL
phoneStringPhone number used for generating DispatchPoint.Attribute is not required.PL
email StringEmail address used for generating DispatchPoint.Attribute is not required.PL

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": "Example of DispatchOrder comment",
	"name": "Example DispatchPoint name",
 	"phone": "505404202",
	"email": "sample@email.com",
	"address": { 
		"id": "123", 
		"street": "Tottenham Court Road", 
		"building_number": "14", 
		"post_code": "W1T 1JY", 
		"city": "London", 
		"country_code": "GB" 
	}
}'

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": "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": [
        {
		 "id": 24,	
		 "comment": "Example of DispatchOrder 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"
}

Possible Errors

  • validation_failed - provided data are incorrect, e.g DispatchPoint not exist or one of shipments is in incorrect status
  • invalid_range - invalid shipment id, e.g range of the id is not matching Integer type
  • dispatch_point_and_address_cannot_be_mixed - address and dispatch_point_id cant be provided at the same time 



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 than new or sent 



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 Organisation with the given ID cannot be found.
  • forbidden - Token does not allow for editing Dispatch Order comments for the given organisation.



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



  • No labels