API

This part of the documentation describes how to communicate directly with the MyParcel.com REST API. For convenience, it is advised that you use the MyParcel.com PHP-SDK whenever possible. If you think you are ready to dive right in, but just want to see all the available resources in more detail you can look at the API resources. For more structural details and examples of the endpoints, see the MyParcel.com OpenAPI specification.

JSON API specification

This section is devoted to give you a little introduction to the JSON API specification. This specification defines how resources should be requested and responses should be formatted. In case you are not familiar with this specification, you will find a reference with some pointers as a quick crash course below.

MIME type

The JSON API specification describes its own media type: application/vnd.api+json. This should be used whenever you include the Content-Type or Accept headers. These headers are not mandatory, since the MyParcel.com API will default to application/vnd.api+json when no headers are specified.

Some endpoints offer exceptions where you are deliberately requesting other file formats. For example when requesting label files, you could use Accept: application/pdf.

Document Structure

Requests to and responses from the API always have the following structure:

A root JSON object with at least 1 of the following:
- data: the documents “primary data”, always either an object, array or null
- errors: an array of error objects
- meta: a meta object that contains non-standard meta-information

For example, the response from the API root:

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
    "meta": {
        "title": "MyParcel.com API",
        "status": "OK"
    },
    "links": {
        "docs": "https://docs.myparcel.com",
        "specification": "https://api-specification.myparcel.com"
    }
}

Note

The data and errors top-level attributes cannot coexist in the same document.

Resource Object, Relationships and Links

Below you will find an example of a simple resource object. It always contains the type of the resource and optionally its id, attributes and relationships to other resources. Normally when requesting a resource, the attributes are present in the response. But for the relationships, the attributes are left out. If you need the attributes of the related resource, you can retrieve it by following the corresponding link.

{
  "data": {
    "type": "shipments",
    "id": "7b808eee-bf1c-40cd-98f2-3c335a06417e",
    "attributes": {
      "recipient_address": "...",
      "sender_address": "...",
      "return_address": "...",
      "description": "Order #8008135",
      "barcode": "3SABCD0123456789",
      "tracking_code": "3SABCD0123456789",
      "price": {
        "amount": 999,
        "currency": "EUR"
      },
      "physical_properties": "..."
    },
    "links": {
      "self": "https://api.sandbox.myparcel.com/shipments/7b808eee-bf1c-40cd-98f2-3c335a06417e"
    },
    "relationships": {
      "shop": {
        "data": {
          "type": "shops",
          "id": "35eddf50-1d84-47a3-8479-6bfda729cd99"
        }
      },
      "service": {
        "data": {
          "type": "services",
          "id": "175a235f-aff5-4e44-87b5-3657b75c1deb"
        }
      },
      "contract": {
        "data": {
          "type": "contracts",
          "id": "2cb32706-5762-4b96-9212-327e6afaeeff"
        }
      }
    }
  }
}

There are two types of links in the above example. The first one is the self link that points to the url where you can request the given resource. Most of the time you won’t be needing this since you already have the resource. But it is there for when you do need it.

The other link looks very similar, but belongs to a relationship. It has the key related and points to the endpoint to retrieve the full resource. The reason this is not called self is because the self link would refer to the relationship itself, instead of the resource that it is pointed towards.

Aside from these self and related links, any kind of useful link could be provided. Like the specification link seen in the API root request example above.

Pagination

Most responses that serve multiple resource items use pagination. The MyParcel.com API offers a few helpers to easily create your own pagination controls or retrieve all items in batches.

As you can see below, the API provides you the total number of pages as well as the total records that can be retrieved. Alongside this is a list of links that correspond to all the actions normally provided by pagination. You could map your own pagination controls to these links (and for example show and hide the next/prev buttons based on the presence of the link in the current response).

You can retrieve all available records by looping through the pagination. As long as there is a next link, there are more records to retrieve. You are done retrieving records as soon as the next link is no longer present in the last response.

{
  "data": [
    {
      "type": "shipments",
      "id": "15d02deb-1601-4c22-a1d7-785a02de3576",
      "attributes": "...",
      "relationships": "...",
      "links": "..."
    },
    {
      "type": "shipments",
      "id": "8de25324-4f4b-4156-bf82-6e66eda349a6",
      "attributes": "...",
      "relationships": "...",
      "links": "..."
    },
    {
      "etc...": "..."
    }
  ],
  "meta": {
    "total_pages": 13,
    "total_records": 373
  },
  "links": {
    "self": "https://api.sandbox.myparcel.com/shipments?page[size]=30&page[number]=3",
    "first": "https://api.sandbox.myparcel.com/shipments?page[size]=30&page[number]=1",
    "prev": "https://api.sandbox.myparcel.com/shipments?page[size]=30&page[number]=2",
    "next": "https://api.sandbox.myparcel.com/shipments?page[size]=30&page[number]=4",
    "last": "https://api.sandbox.myparcel.com/shipments?page[size]=30&page[number]=13"
  }
}

Pagination query parameters

These are the query parameters used for pagination:

Parameter	Description	Value	Default
page[size]	Determines how many records to retrieve per page	Any number higher than 0 and lower than or equal to the max record size	100
page[number]	Indicates from which page the records should be retrieved	Any number higher than 0	1

Together, these parameters will cause the API to return a specific range of resources based on your input. For example, a combination of page[size]=8 and page[number]=3 will retrieve 8 records: number 17 to 24.

When an unsupported value (-1 for example) is used for one of the parameters the default value will be used instead. If a positive page number is used that is higher than the amount of existing pages, the API won’t be able to find any records and will simply return an empty array.

Max record size

The default max record size is 100.

Errors

If the top-level errors attribute exists, it can contain one of the following errors:

Error code	Error number	Description
NOT_FOUND	10000	The requested endpoint could not be found.
INTERNAL_SERVER_ERROR	10001	An internal server error has occurred, this is usually a problem on the MyParcel.com end. Please contact support if it persists.
RESOURCE_NOT_FOUND	10002	The resource you are trying to get the data of could not be found.
INVALID_JSON_SCHEMA	10003	The request does not conform to the MyParcel.com API specification.
INVALID_REQUEST_HEADER	10004	One or more of your request headers is invalid.
RESOURCE_CANNOT_BE_MODIFIED	10005	Either this resource can’t be modified or you do not have permission to modify this resource.
INVALID_ERROR_SCHEMA	10006	An error was thrown during the request to an external source. No more information can be provided since the returned error was improperly formatted.
RESOURCE_CONFLICT	10007	The `type` or `id` of one of the resources was not computable or the resource `id` is not valid.
UNPROCESSABLE_ENTITY	10008	The server understands the content type and the syntax is correct, but the server was unable to process the contained instructions.
MISSING_BILLING_INFORMATION	11000	In order to complete this request, some missing billing information should be provided first.
EXTERNAL_REQUEST_ERROR	13001	An error occurred while making a request to an external service. When available, details can be found in the meta of the response.
CARRIER_API_ERROR	13002	There was a problem with the request to the carrier. The original response can be found in the meta under `carrier_response`.
AUTH_INVALID_CLIENT	14000	The supplied client credentials are invalid or the client does not have access to this grant type.
AUTH_INVALID_SCOPE	14001	The requested scope is not available for your client.
AUTH_INVALID_TOKEN	14002	The provided access token does not seem to be valid.
AUTH_MISSING_TOKEN	14003	An access token is required but no access token was provided.
AUTH_MISSING_SCOPE	14004	The used access token does not contain the required scope(s).
AUTH_SERVER_EXCEPTION	14050	Unable to process the OAuth request. This is a generic OAuth error with no direct known cause. Please contact support if the problem persists.

The error responses conform to the JSON API standard. For more information about what they might contain, visit the errors section of the specification.