To show delivery options to customers, you can use our javascript code. Use our sandbox for an example and easier integration.

1. Requests

1.A Base URL

BaseURL: https://api.sendmyparcel.be

1.B User-Agent

To give us insight that you use the API documentation, you should always send an User-Agent in your header. If you do not use a known CMS system, use the following header:
User-Agent: CustomApiCall/2

If you are using a known CMS system then you must use the name of the CMS system followed by a version number (User-Agent: <product> / <product-version>). Here's an example if your CMS system is Wordpress: User-Agent: Wordpress/4.8.1.

1.C HTTP methods

The API is REST(ful) and uses JSON as it's primary data exchange format. Communication with the API goes through HTTPS thereby insuring data confidentiality and integrity. Here is a list of all supported HTTP methods

1.C.1 GET

GET method is used for retrieving data and is idempotent. Data can be returned in JSON, PDF, CSV, XML or other formats.

1.C.2 POST

POST is used to create new objects or send data to MyParcel.

1.C.3 DELETE

DELETE is used to delete an existing object (piece of data). This method always returns HTTP/1.1 204 No Content unless otherwise specified.

2. Responses

As stated earlier data is usually send back in JSON format. Exceptions to this rule are shipment label, invoice and CSV export. Shipment label and invoice are send back in PDF format while CSV export is send back in CSV format. Usually a response will have a response body. Exceptions are DELETE requests which will only contain a status code (204) indicating success. A failed request with a 4xx status code will always send back a response body with the error description. A failed request with a 5xx status code will probably mean you've hit a snag in our API. We try to monitor these kind of errors, but if you keep having trouble... Don't hesitate to reach out!

2.A HTTP statuses

HTTP status codes are used to indicate success or failure of a request. Here's a list of supported status codes. For a more comprehensive list of HTTP status codes visit Wikipedia or W3C.

Example of a 200 Status code in our API (you can try this in your browser, then you know our API is online)

GET https://api.sendmyparcel.be/
Request Headers (example!):
GET / HTTP/1.1
Host: api.sendmyparcel.be
Connection: keep-alive
Pragma: no-cache
Cache-Control: no-cache
Upgrade-Insecure-Requests: 1
Accept-Encoding: gzip, deflate, sdch, br

{
  "title":"MyParcel API",
  "status":"OK"
}
Response Headers (example!)
HTTP/1.1 200 OK
Date: Tue, 31 Jan 2017 13:37 GMT
Content-Type: application/json;charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive

2.A.I 2xx

Used for successful requests. Successful requests may contain a response body e.g. object id of new object or none when modifying an existing object.

2.A.I 200 - OK

This status code is used for successful requests that have a response body.

2.A.I 202 - Accepted

This status code is used for requests that have been received successfully and will be processed at a later time. This is mostly used for processing shipments and addresses CSV.

2.A.I 204 - No Content

This status is used primarily for DELETE requests.

2.A.II 3xx

2.A.II 304 - Not Modified

This status is used by the server when the resource is the same the one the client has.

2.A.III 4xx

Used for failed requests. Failed requests always contain a response body with the error description.

2.A.III 400 - Bad Request

When the request received is malformed.

2.A.III 401 - Unauthorized

No credentials have been sent with the request. Or the wrong credentials are send. Tip: check if the API key is properly attached in the header

Authorization: basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==

2.A.III 402 - Payment Required

When payment is required. An Invoice object is always sent with this response.

2.A.III 403 - Forbidden

When the given credentials are not authorized to perform a certain action.

2.A.III 404 - Not Found

When a resource cannot be found.

2.A.III 405 - Method not allowed

When you used a method on an endpoint that is either not supported or not allowed for the given credentials.

2.A.III 406 - Not acceptable

When the client requests a given format for a resource that is not supported.

2.A.III 415 - Unsupported media type

When the client specifies a content-type in the request that is not supported.

2.A.III 422 - Unprocessable Entity

When the client sends a request object with invalid data. The error message will specify what's wrong with the Request or the Data send to the API.

2.A.III 409 - Conflict

When the client request conflicts with the current state of the resource.

2.A.IV 5xx

Used for server-side errors. This happens when we (i.e. MyParcel.nl / the API) are having problems.

3. Character encoding

All content must be encoded in UTF-8 and include the charset=utf-8.

example:

Content-Type: application/json;charset=utf-8

4. Data Types

Our API defines it's own data types.

4.1 Contents

• array
• boolean
• carrier
• country_code
• currency
• date
• delivery_type
• integer
• coordinates
• isic_code
• label_position
• month_digit
• package_contents
• package_type
• paper_size
• price
• shipment_status
• sort_order
• string
• text
• time
• timestamp
• weekday_digit
• weekday_string

array

boolean

carrier

country_code

currency

date

delivery_type

integer

coordinates

isic_code

label_position

month_digit

package_contents

The package contents are only needed in case of shipping outside EU, this is mandatory info for customs form

package_type

paper_size

price

shipment_status

sort_order

string

text

time

timestamp

weekday_digit

weekday_string

5. Authentication

HTTP basic access authentication on top of SSL is used for authentication. Every request must include an Authorization header with base64 encoded API Key. Go to base64encode.org to convert your key base64.

GET /somelink HTTP/1.1
Authorization: basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==

Our API uses API keys for access control. When a Merchant wants to connect an external system to our API he/she needs to create an API Key. This API Key will be assigned the Broker role. Currently the Merchant is not able to create or assign another Role to a API Key. When the Merchant wants to invalidate an API Key he/she just disables the API Key. An Intermediate system, such as the MyParcel UI, has its own API Key but cannot access user resources. For this it needs to request a Session Token so that it can perform actions on behalf of the user. The API Key and Session Token are send in the Authorization header.

5.1 Error codes

Our API defines a list of error codes besides the HTTP status codes. Error codes are divided in ranges to make it easier for developers to quickly diagnose and solve problems. Errors are returned as an Error object.

6. Shipments

We’ll start the shipment section with the different shipment option combinations available in MyParcel (6.a). It is highly recommended that you read this first as this section helps you understand what all the shipment options are and which combinations are possible. We will not list every possible combination since there are too many to list. We will look at the different package types and then look at the different options available to them. Then we bring all of it together with some examples.

6.A Shipment option combinations

Contents

6.A.1 Package types

The package type. For MyParcel BE only package type 1 (package) is available. The value is send with the ShipmentOptions.package_type field.

Package

This is the standard package type used for BE, EU and Global shipments. It supports a variety of additional options such as insurance, signature etc. We will look at these options in more detail later.

6.A.2 Delivery types

There are two different delivery types and these specify how the package is delivered. The value is send with the ShipmentOptions.delivery_type field.

Standard

This is the standard delivery type.

Pickup

The package is delivered at the chosen drop off point specified by the Consumer/Customer.

6.A.3 Options

These are the different package options. These options are specified in the ShipmentOptions object.

signature

Recipient must sign for the package. This option is required for Pickup delivery. Signature is only possible for a shipment with carrier: 2 (bpost)

insurance

This option allows a shipment to be insured up to certain amount. BE, EU and Global shipments can be insured for 500,- euros. The shipment option signature are mandatory when insuring a shipment.

6.A.4 Examples

Pickup

We want to send a package to a consumer in Antwerpen. He will pick the package up at the nearest pickup location. The shipment looks like this:

    {
      "data": {
        "shipments": [{
          ...
          "options": {
            "package_type": 1,
            "signature": 1,
            "delivery_type": 4
          },
          "pickup": {
            ...
          }...
        }]
      }
    }

Let's go through this example. This package will be picked up by the customer so it needs to package_type 1(package) with delivery type 4 (Pickup). All pickup packages need to have signature set. A pickup location needs to be specified as well.

NL insured

We want to send a Rolex to a customer in Maastricht. This shipment needs to be insured up to 50000 euros. The shipment looks like this.

    {
      "data": {
        "shipments": [{
          ...
          "options": {
            "package_type": 1,
            "insurance": {
              "amount": 50000,
              "currency": "EUR"
            },
            "signature": 1,
              ...
          }
        }]
      }
    }

Insurance amount needs to be specified in cents and needs to be 50000. The package needs to be insured up to 500 euros so we set insurance.amount to 50000 cents.

EU and Global insured

We want to send an expensive Japanese vase to a Dutch friend of ours in Amsterdam. Since this is an EU shipment is must be insured up to 500 euros.

  {
    "data": {
      "shipments": [{
        ...
        "options": {
          "package_type": 1,
          "insurance": {
            "amount": 50000,
            "currency": "EUR"
          }
        }
        ...
      }]
    }
  }

This package is an EU package so the type must be set to 1. All EU and Global shipments must be insured up to 500 (EU) euros so we set the insured amount to 50000 cents. EU and Global shipments do not have the signature and return options so these cannot be set for this shipment.

6.B Add Shipment

6.B.1 Overview

For JSON requests a ShipmentIds object is returned.

6.B.2 Reference

6.B.3 Request Headers

Content-Type: application/vnd.shipment+json
Specify this content-type when you want to create standard shipments.

Content-Type: application/vnd.return_shipment+json
Parent shipment cannot be a concept (shipment_status 1).
When a label is generated, the status of the shipment is converted to registered (shipment_status 2).

Content-Type: application/vnd.unrelated_return_shipment+json
Specify this content-type when you want to create unrelated return shipments.

6.B.4 Examples

For these examples we are going to create shipments.

Create national bpost shipments

Request

POST https://api.sendmyparcel.be/shipments HTTP/1.1
Content-Type:application/vnd.shipment+json;charset=utf-8
User-Agent: CustomApiCall/2
Authorization:basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==
{
  "data": {
    "shipments": [
      {
        "recipient": {
          "cc": "BE",
          "postal_code": "2000",
          "city": "Antwerpen",
          "street": "Wormerplein",
          "number": "16",
          "box_number": "",
          "person": "test"
        },
        "options": {
          "package_type": 1,
          "signature": 0,
          "insurance": {
            "amount": 0,
            "currency": "EUR"
          }
        },
        "carrier": 2,
        "reference_identifier": "bpost shipment"
    }]
  }
}

Response

HTTP/1.1 200 OK Content-Type:application/json;charset=utf-8
{
    "data": {
        "ids": [
            {
                "id": 49566653,
                "reference_identifier": "bpost shipment"
            }
        ]
    }
}

Create national DPD shipments

Request

POST https://api.sendmyparcel.be/shipments HTTP/1.1
Content-Type:application/vnd.shipment+json;charset=utf-8
User-Agent: CustomApiCall/2
Authorization:basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==
{
  "data": {
    "shipments": [
      {
        "recipient": {
          "cc": "BE",
          "postal_code": "2000",
          "city": "Antwerpen",
          "street": "Wormerplein",
          "number": "16",
          "box_number": "",
          "person": "test"
        },
        "options": {
          "package_type": 1
        },
        "carrier": 4,
        "reference_identifier": "Order 123456"
    }]
  }
}

Response

HTTP/1.1 200 OK Content-Type:application/json;charset=utf-8
{
"data": {
    "ids": [
        {
            "id": 49566517,
            "reference_identifier": "Order 123456"
        }
    ]
}

Create International bpost shipment

Request

POST https://api.sendmyparcel.be/shipments HTTP/1.1
Content-Type:application/vnd.shipment+json; charset=utf-8
User-Agent: CustomApiCall/2
Authorization:basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==
{
  "data": {
    "shipments": [{
      "recipient": {
        "cc": "JP",
        "region": "埼玉県",
        "city": "さいたま市",
        "street": "埼玉県さいたま市浦和区 常盤9－21－21",
        "number": "12",
        "postal_code": "12345",
        "person": "Tanaka san",
        "company": "さいたま国際キリスト教会",
        "email": "saitamakyokai@gmail.com",
        "phone": "0081-48-825-6637"
      },
      "options": {
        "package_type": 1
      },
        "customs_declaration": {
          "contents": 1,
          "items": [
            {
              "country": "BE",
              "item_value": {
                "amount": 10000,
                "currency": "EUR"
              },
              "description": "1",
              "amount": 1,
              "weight": 3000,
              "classification": ""
            }
          ],
          "weight": 3000
        },
        "physical_properties": {
          "weight": 1000
        },
      "carrier": 2
    }]
  }
}

Response

HTTP/1.1 200 OK Content-Type:application/json; charset=utf-8
{
  "data": {
    "ids": [{
      "id": 3485394579
    }]
  }
}

Create bpost shipment with BE pickup location

Request

POST https://api.sendmyparcel.be/shipments HTTP/1.1
Content-Type:application/vnd.shipment+json; charset=utf-8
User-Agent: CustomApiCall/2
Authorization:basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==
{
  "data": {
    "shipments": [
      {
        "carrier": 2,
        "recipient": {
          "cc": "BE",
          "city": "Antwerpen",
          "street": "Adriaan Brouwerstraat",
          "number": "16",
          "person": "Test",
          "postal_code": "2000"
        },
        "options": {
          "package_type": 1,
          "delivery_type":4
        },
        "pickup": {
          "city": "ANTWERPEN",
          "location_code": "618925",
          "location_name": "KLAPKRANT",
          "number": "15",
          "postal_code": "2000",
          "street": "KLAPDORP"
        },
        "reference_identifier": "order-012356"
      }
    ]
  }
}

Response

HTTP/1.1 200 OK Content-Type:application/json; charset=utf-8
{
    "data": {
        "ids": [
            {
                "id": 49571535,
                "reference_identifier": "order-012356"
            }
        ]
    }
}

Create DPD shipment with BE pickup location

Request

POST https://api.sendmyparcel.be/shipments HTTP/1.1
Content-Type:application/vnd.shipment+json; charset=utf-8
User-Agent: CustomApiCall/2
Authorization:basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==
{
  "data": {
    "shipments": [
      {
        "carrier": 4,
        "recipient": {
          "cc": "BE",
          "city": "Antwerpen",
          "street": "Adriaan Brouwerstraat",
          "number": "16",
          "person": "Test",
          "postal_code": "2000"
        },
        "options": {
          "package_type": 1,
          "delivery_type":4
        },
        "pickup":{
           "postal_code":"2000",
           "location_name":"PRESS WINKEL",
           "city":"Antwerpen",
           "street":"HOOGSTRAAT",
           "number":"75",
           "cc":"BE",
           "location_code":"BE11468"
        },
        "reference_identifier": "DPD pickup"
      }
    ]
  }
}

Response

HTTP/1.1 200 OK Content-Type:application/json; charset=utf-8
{
    "data": {
        "ids": [
            {
                "id": 49571535,
                "reference_identifier": "DPD pickup"
            }
        ]
    }
}

Create unrelated return shipment

Request

POST https://api.sendmyparcel.be/shipments
HTTP/1.1
Content-Type: application/vnd.unrelated_return_shipment+json;charset=utf-8
User-Agent: CustomApiCall/2
Authorization:basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==
{
  "data": {
    "return_shipments": [{
      "options": {
        "package_type": 1,
        "signature": 0,
        "return": 0,
        "insurance": {
          "amount": 0,

        "label_description": "My custom description"
      },
      "carrier": 2,
      "email": "testing@sendmyparcel.be",
      "name": "Test"
    }]
  }
}

Response

HTTP/1.1 200 OK Content-Type:application/json; charset=utf-8
{
  "data": {
    "ids": [{
      "id": 12345
    }]
  }
}

6.C Delete Shipment

Note: The ‘Delete shipment’ section is not used often. This can only be done for shipments for which a label has not yet been created (status 1). Especially since shipments not handed over to the distributor will not be billed by MyParcel. Therefore, when unused shipments are not deleted this has no financial consequences.

6.C.1 Overview

Use this link to remove shipments. You can specify multiple shipment ids by semicolon separating them on the URL. Only shipments with status 'pending - concept' can be deleted. This method returns HTTP/1.1 204 if successful. If the shipment doesn’t exist a 422 "cannot delete shipment" is returned.

6.C.2 Reference

6.C.3 Parameters

id
Data type: integer
The id of the shipment to delete. You can specify multiple shipments by semi-colon separating them.

6.C.4 Example

Remove a shipment with id 1234.

Request

DELETE https://api.sendmyparcel.be/shipments/1234 HTTP/1.1
User-Agent: CustomApiCall/2
Authorization:basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==

Response

HTTP/1.1 204 No Content 

6.D Generate unrelated return shipment url

6.D.1 Overview

This endpoint is often used by external parties to facilitate return shipments on a dedicated part of their website, mainly when offering reverse logistics e.g. repair services. It will allow the consumer to send packages to the merchant directly from the merchant's website. If this option is not enable then HTTP/1.1 404 Not Found is returned.

6.D.2 Reference

6.D.3 Example

Proceed with actual request
Request

POST https://api.sendmyparcel.be/return_shipments
User-Agent: CustomApiCall/2
HTTP/1.1 Authorization: basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==

Response

HTTP/1.1 200 OK  Content-Type:application/json
{
  "data": {
    "download_url": {
     "link": "https://api.sendmyparcel.be/return_shipment_labels/902223ede2f50288ecfbbd21a8c8fd7e"
     }
  }
}

PHP Examples README

If you are a PHP Developer we've included a few examples on how to call our API from your (custom) back-end. For cURL / Non-cURL PHP examples: click here.

6.E Get Shipment

6.E.1 Overview

With this endpoint you can get shipments. You can use the 'q' query parameter to search for shipments. Depending on the Accept request header either JSON or CSV is returned. Multiple shipment ids can be specified on the URI by using semi-colon. There are limitation when getting data back as CSV. When using CSV you will only get the most recent status of shipment.

Upon success either a JSON array of Shipment objects or a CSV file is returned.

6.E.2 Reference

6.E.3 Parameters

id
Data type: integer
This is the shipment id. You can specify multiple shipment ids by semi-colon separating them on the URI.

reference_identifier
Data type: string
This is an optional arbitrary identifier to identify the shipment.

dropoff_today
Data type: boolean
Use this parameter to filter for shipments that need to dropped at a PostNL location today.

q
Data type: string
Use this parameter to search trough all the fields of a shipment object including the embedded objects

status
Data type: shipment_status
Use this parameter to specify the shipment status to filter on. You can specify multiple status by semi-colon separating them on the URI.

from
Data type: date
Use this parameter to filter on the shipment creation date. This filter will set the lower bound of the date search range.

to
Data type: date
Use this parameter to filter on the shipment creation date. This filter will set the upper bound of the date search range.

page
Data type: integer
Page number. Maximum value is 1000 and minimum is 1. Defaults to 1.

size
Data type: integer
Items per page. Maximum value is 200 and minimum is 30. Defaults to 30.

sort
Data type: string
Shipment object field to sort on. See Shipment object

order
Data type: sort_order
Sort order for sort filter. Defaults to ASC.

6.E.4 Example

JSON

Search for shipments
Search shipments for fields containing 'Niels' with status 'pending'. The first shipment has 'Jan' in the person field.

Request

GET https://api.sendmyparcel.be/shipments?q=Niels&;status=1
User-Agent: CustomApiCall/2
HTTP/1.1 Authorization: basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==

Response

HTTP/1.1 200 OK Content-Type:application/json; charset=utf-8
{
  "data": {
    "search_results": {
      "shipments": [{
            "id": 32879749,
            "parent_id": null,
            "account_id": 108164,
            "shop_id": 18432,
            "shipment_type": 1,
            "recipient": {
                "cc": "BE",
                "postal_code": "2000",
                "city": "Purmerend",
                "street": "Wormerplein",
                "number": "16",
                "box_number": "",
                "person": "test"
            },
            "sender": {
                "cc": "BE",
                "postal_code": "2000",
                "city": "Hoofddorp",
                "street": "Siriusdreef",
                "number": "16",
                "number_suffix": "",
                "person": "MyParcel",
                "company": "MyParcelNL",
                "email": "richard@myparcel.nl",
                "phone": "0233030315"
            },
            "status": 2,
            "options": {
                "package_type": 1,
                "signature": 0,
                "insurance": {
                    "amount": 0,
                    "currency": "EUR"
                },
                "delivery_type": 2
            },
            "general_settings": {
                "save_recipient_address": 0,
                "tracktrace": {
                    "send_track_trace_emails": 1,
                    "email_on_handed_to_courier": 1,
                    "bcc": 1,
                    "bcc_email": "richard@myparcel.nl",
                    "from_address_email": "richard@myparcel.nl",
                    "from_address_company": "MyParcel test123",
                    "delivery_notification": 1,
                    "carrier_email_basic_notification": 1
                },
                "delivery_notification": 1,
                "delivery_notification_email": [
                    "richard@myparcel.nl"
                ]
            },
            "pickup": null,
            "customs_declaration": null,
            "physical_properties": null,
            "created": "2018-05-07T00:00+02:00",
            "modified": "2018-05-07T16:25:01+02:00",
            "reference_identifier": null,
            "created_by": 16441,
            "modified_by": 16441,
            "transaction_status": "unpaid",
            "price": {
                "amount": 0,
                "currency": "EUR"
            },
            "barcode": "323211623959926381769040",
            "region": "NL",
            "payment_status": "unpaid"
        }],
        "results": 1
      }
    }
  }

6.F Get Shipment label

6.F.1 Overview

Get shipment label. You can specify label format and starting position of labels on the first page with the format and position query parameters. The position query only works when you specify the A4 format and is only applied on the first page with labels.
Accounts with Postpayment payment methods can fetch multiple labels in one call. For accounts with Prepayment payment method a HTTP/1.1 402 Payment Required with a PaymentInstructions object is returned if the label has not been paid for yet.

Upon error HTTP/1.1 4xx < MESSAGE > with a response body containing an Error is returned.

6.F.2 Reference

6.F.3 Parameters

id
Data type: integer
This is the shipment id. You can specify multiple shipment ids by semi-colon separating them on the URI.

format
Data type: paper_size
The paper size of the PDF. Currently A4 and A6 are supported. When A4 is chosen you can specify the label position.
When requesting the label for a shipment that contains a custom form, you can only request a A4 format.

positions
Data type: label_position
The position of the label on an A4 sheet. You can specify multiple positions by semi-colon separating them on the URI. Positioning is only applied on the first page with labels. All subsequent pages will use the default positioning 1,2,3,4.

6.F.4 Example

Get Shipment label

Request

GET https://api.sendmyparcel.be/shipment_labels/12 HTTP/1.1
User-Agent: CustomApiCall/2
Authorization: basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==

Response

HTTP/1.1 200 OK Content-Disposition: attachment;
filename="123123123.pdf" Content-Type: application/pdf
(...PDF content)

Get shipment label download link

Request

GET https://api.sendmyparcel.be/shipment_labels/12 HTTP/1.1
User-Agent: CustomApiCall/2
Authorization: basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==
Accept: application/json;charset=utf-8

Response

    HTTP/1.1 200 OK Content-Type:application/json;charset=utf-8
    {
      "data": {
        "pdfs": {
          "url": "https://api.sendmyparcel.be/pdfs/461efc8b5c7e71dbd0c39a25067bda9455b0ca5a"
        }
      }
    }

Get shipment label with different format and position
Get label for shipment with id 2. The label will be printed on an A4 sheet and the label position will be at the bottom-right.

Request

GET https://api.sendmyparcel.be/shipment_labels/2?format=A4&positions=3;4 HTTP/1.1
User-Agent: CustomApiCall/2
Authorization: basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==

Response

HTTP/1.1 200 OK Content-Disposition: attachment; filename="456456456456.pdf" Content-Type:
application/pdf (...PDF content)

6.G Track Shipment

6.G.1 Overview

Get detailed track and trace information for a shipment. Upon success HTTP/1.1 200 OK is returned with an array of TrackTrace objects.

6.G.2 Reference

6.G.3 Parameters

id
Data type: integer
This is the shipment id. You can specify multiple shipment ids by semi-colon separating them on the URI.

page
Data type: integer
Page number. Maximum value is 1000 and minimum is 1. Defaults to 1.

size
Data type: integer
Items per page. Maximum value is 200 and minimum is 30. Defaults to 30.

sort
Data type: string
TrackTrace object field to sort on. See TrackTrace

order
Data type: sort_order
Sort order for sort filter. Defaults to ASC.

6.G.4 Example

Request

            GET https://api.sendmyparcel.be/tracktraces/12 HTTP/1.1
            User-Agent: CustomApiCall/2
            Authorization: basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==

Response

HTTP/1.1 200 OK Content-Type:application/json; charset=utf-8
{
  "data": {
    "tracktraces": [{
      "shipment_id": "1234",
      "code": "D3",
      "final": false,
      "description": "The package is in distribution",
      "time": "2015-01-02 05:00",
      "history": [{
        "code": "C3",
        "description": "The package is at the sorting center",
        "time": "2015-01-02 05:00"
      }, {
        "code": "B2",
        "description": "The package is has been scanned",
        "time": "2015-01-01 06:00"
      }]
    }, {
      "shipment_id": "569034234",
      "code": "B4",
      "description": "The package is at the sorting center",
      "time": "2015-01-02 05:00",
      "history": [{
        "code": "A2",
        "description": "The package has been scanned",
        "time": "2015-01-01 05:00"
      }]
    }]
  }
}

7. Shipment related Object Definitions

7.A Shipment Object Definition

7.A.1 Overview

You can create shipments with this object. You can specify multiple address ids in the recipients column to create multiple shipments. If you want to create a return shipment you have to use the ReturnShipment object.

barcode
Data type: string
Required: n/a.
Shipment barcode.

id
Data type: integer
Required: n/a.
Shipment id.

parent_id
Data type: integer
Required: no
The parent shipment. This is used for related return shipment.

account_id
Data type: integer
Required: n/a.
The account id to which this shipment belongs.

shop_id
Data type: integer
Required: n/a.
The shop id to which this shipment belongs.

reference_identifier
Data type: string
Required: No.
Arbitrary reference indentifier to identify this shipment.

shipment_type
Data type: integer
Required: n/a.

recipient
Data type: Address
Required: Yes for application/vnd.shipment+json
The recipient address. Use this field when you want to create a shipment for one address.

recipients
Data type: array of Address objects
Required: Yes for application/vnd.shipment_recipients+json Use this field when you want to create multiple shipments for multiple addresses.

sender
Data type: Address
Required: n/a.
The sender of the package. This field is never set.

status
Data type: shipment_status
Required: no
This is the internal shipment status. What we do is filter and translate the shipment status provided by the carrier in order to reduce the number of statusses.

options
Data type: ShipmentOptions
Required: Yes.
The shipment options.

pickup
Data type: PickupLocation
Required: Yes for options.delivery_type 4.
The pickup location for this shipment.

customs_declaration
Data type: CustomsDeclaration
Required: yes for non-EU shipments.
The customs declaration information.

physical_properties
Data type: PhysicalProperties
Required: Yes.
Shipment physical properties such as dimension, weight etc. This object may be updated when fetching shipment status update from the carrier.

carrier
Data type: carrier
Required: yes.
The carrier that will deliver the package.

general_settings
Data type: ShipmentGeneralSettings
Required: no
You can specify general settings for the shipment with this object.

price
Data type: price
Required: n/a.
The shipment price.

created
Data type: timestamp
Required: n/a.
Date of creation.

modified
Data type: timestamp
Required: n/a.
Date of modification.

7.A.2 Example

POST example national shipment

{
  "data": {
    "shipments": [
      {
        "recipient": {
          "cc": "BE",
          "postal_code": "2000",
          "city": "Antwerpen",
          "street": "Wormerplein",
          "number": "16",
          "box_number": "",
          "person": "test"
        },
        "options": {
          "package_type": 1,
          "signature": 0,
          "insurance": {
            "amount": 5000,
            "currency": "EUR"
        },
        "carrier": 2
      }

POST example national shipment b

{
  "data": {
    "shipments": [
      {
        "recipient": {
          "cc": "BE",
          "postal_code": "2000",
          "city": "Antwerpen",
          "street": "Wormerplein",
          "number": "16",
          "box_number": "",
          "person": "test"
        },
        "options": {
          "package_type": 1,
          "signature": 0,
          "insurance": {
            "amount": 0,
            "currency": "EUR"
        },
        "carrier": 2
      }

POST example international shipment

{
  "data": {
    "shipments": [
      {
		"reference_identifier" : "Order 1",
        "recipient": {
          "cc": "JP",
          "region": "埼玉県",
          "city": "さいたま市",
          "street": "埼玉県さいたま市浦和区 常盤9-21-21",
          "company": "さいたま国際キリスト教会",
          "email": "saitamakyokai@gmail.com",
          "phone": "0081488256637",
          "person": "test"
        },
        "options": {
          "package_type": 1
        },
        "customs_declaration": {
	        "contents": 1,
	        "weight": 3000,
	        "items":[{
		      "description": "Sample Product",
		      "amount": 10,
		      "weight": 20,
	    		"item_value": {
	        	"amount": 7000,
	        	"currency": "EUR"
	    		},
			      "classification": "0181",
			      "country": "NL"
	    	  }
    		]
        },
		  "physical_properties": {
		    "weight": 4000
		},
        "carrier": 2
      }
    ]
  }
}

POST example pickup location

{
  "data": {
    "shipments": [{
      "recipient": {
        "cc": "BE",
        "region": "Antwerpen",
        "city": "Antwerpen",
        "street": "Adriaan Brouwerstraat",
        "number": "16",
        "postal_code": "2000",
        "person": "Mr. Parcel",
        "phone": "0213030315",
        "email": "testing@sendmyparcel.be"
      },
      "options": {
        "package_type": 1,
        "delivery_type": 4
      },
      "carrier": 2
    }]
  }
}

GET example national shipment

{
    "data": {
        "shipments": [
            {
                "id": 32904375,
                "parent_id": null,
                "account_id": 108164,
                "shop_id": 18432,
                "shipment_type": 1,
                "recipient": {
                    "cc": "BE",
                    "region": "Antwerpen",
                    "city": "Antwerpen",
                    "street": "Adriaan Brouwerstraat",
                    "number": "16",
                    "box_number": "12",
                    "postal_code": "2000",
                    "person": "Mr. Parcel",
                    "phone": "0213030315",
                    "email": "testing@sendmyparcel.be"
                },
                "sender": {
                    "cc": "BE",
                    "postal_code": "2000",
                    "city": "Hoofddorp",
                    "street": "Siriusdreef",
                    "number": "16",
                    "number_suffix": "",
                    "person": "MyParcel",
                    "company": "MyParcelNL",
                    "email": "richard@myparcel.nl",
                    "phone": "0233030315"
                },
                "status": 1,
                "options": {
                    "package_type": 1,
                    "delivery_type": 4
                },
                "general_settings": {
                    "save_recipient_address": 0,
                    "tracktrace": {
                        "send_track_trace_emails": 1,
                        "email_on_handed_to_courier": 1,
                        "bcc": 1,
                        "bcc_email": "richard@myparcel.nl",
                        "from_address_email": "richard@myparcel.nl",
                        "from_address_company": "MyParcel test123",
                        "delivery_notification": 1,
                        "carrier_email_basic_notification": 1
                    },
                    "delivery_notification": 1,
                    "delivery_notification_email": [
                        "richard@myparcel.nl"
                    ]
                },
                "pickup": null,
                "customs_declaration": null,
                "physical_properties": null,
                "created": "2018-05-08T00:00+02:00",
                "modified": "2018-05-08T12:51+02:00",
                "reference_identifier": null,
                "created_by": 16441,
                "modified_by": 16441,
                "transaction_status": "unpaid",
                "barcode": "",
                "price": {
                    "amount": 0,
                    "currency": "EUR"
                },
                "region": "NL",
                "payment_status": "unpaid"
            }
        ],
        "results": 1817
    }
}

7.B Address Object Definition

7.B.1 Overview

This is the adress object

cc
Data type: country_code
Required: yes.
The address country code.

region
Data type: string
Required: no.
The region, department, state or province of the address.

postal_code
Data type: string
Required: Yes for BE and EU destinations except for IE.
The address postal code.

city
Data type: string
Required: yes.
The address city.

street
Data type: string
Required: yes.
The address street name max 40 characters.

number
Data type: string
Required: Yes for BE.
House number.

box_number
Data type: string
Required: no
Additional house number.

person
Data type: string
Required: yes.
The person at this address.

company
Data type: string
Required: no.
Company name.

email
Data type: string
Required: no
The address email.

phone
Data type: string
Required: no.
The address phone.

7.B.2 Example

Example a

{
    "cc": "BE",
    "region": "Antwerpen",
    "city": "Antwerpen",
    "street": "Adriaan Brouwerstraat",
    "number": "16",
    "postal_code": "2000",
    "person": "Mr. Parcel",
    "phone": "0213030315",
    "email": "testing@sendmyparcel.be"
}

Example b

{
    "cc": "BE",
    "region": "Antwerpen",
    "city": "Antwerpen",
    "street": "Adriaan Brouwerstraat",
    "number": "16",
    "box_number": "12",
    "box_number": "12",
    "postal_code": "2000",
    "person": "Mr. Parcel",
    "phone": "0213030315",
    "email": "testing@sendmyparcel.be"
}

Example c

{
  "cc": "FR",
  "region": "Seine",
  "city": "Paris",
  "street": "rue du Grenier-Saint-Lazare 22",
  "person": "Claus Stuter",
  "company": "Renault",
  "email": "claus@paris.nl",
  "postal_code": "75008",
  "phone": "0033142723122"
}

Example d

{
    "cc": "BE",
    "region": "Antwerpen",
    "city": "Antwerpen",
    "street": "Adriaan Brouwerstraat",
    "number": "16",
    "postal_code": "2000",
    "person": "Mr. Parcel",
    "phone": "0213030315",
    "email": "testing@sendmyparcel.be"
}

Example e

{
    "cc": "BE",
    "region": "Antwerpen",
    "city": "Antwerpen",
    "street": "Adriaan Brouwerstraat",
    "number": "16",
    "person": "Mr. Parcel",
    "company" "Renault B.V."
    "phone": "0213030315",
    "email": "testing@sendmyparcel.be"
}

Example i

{
  "cc": "JP",
  "region": "埼玉県",
  "city": "さいたま市",
  "street": "埼玉県さいたま市浦和区 常盤9－21－21",
  "person": "Tanaka san",
  "company": "さいたま国際キリスト教会",
  "email": "saitamakyokai@gmail.com",
  "phone": "0081-48-825-6637"
}

Example CSV a

{
  "cc",
  "city",
  "street",
  "number",
  "person",
  "company",
  "email",
  "phone",
  "groups""124",
  "be",
  "Antwerpen",
  "Adriaan Brouwerstraat",
  "16",
  "Claus Stuter",
  "MyParcel B.V.",
  "claus@stuter.nl",
  "0203030315",
}

Example CSV b

{
  "cc",
  "postalcode",
  "city",
  "street",
  "number",
  "person",
  "company",
  "email",
  "phone""be",
  "2000",
  "Antwerpen",
  "Adriaan Brouwerstraat",
  "16",
  "Mrs. Parcel",
  "MyParcel",
  "parcel@sendmyparcel.be",
  "0213030315"
}

Example CSV c

{
  "be",
  "2000",
  "Antwerpen",
  "Adriaan Brouwerstraat",
  "16",
  "Arie Test",
  "MyParcel",
  "arie@sendmyparcel.be",
  "0213030319"
}

7.C ShipmentGeneralSettings Object Definition

7.C.1 Overview

You can specify shipment general settings with this object. It is embedded in the Shipment.general_settings column.

save_recipient_address
Data type: boolean
Required: No
When this setting is true the recipient address will be saved in the address book. Only for valid for POST request.

delivery_notification
Data type: boolean
Required: No.
When this setting is true the Merchant will receive an email notification when the package has been delivered.

delivery_notification_email
Data type: array of string
Required: No.
This email addresses that will receive a delivery notification.

7.C.2 Example

Example

{
  "save_recipient_address": 1,
  "delivery_notification": 1,
  "delivery_notification_email": "testing@sendmyparcel.be"
}

7.D CustomsDeclaration Object Definition

7.D.1 Overview

This object is embedded in the Shipment object for global shipments and is mandatory for non-EU shipments.

contents
Data type: package_contents
Required: Yes.
The type of contents in the package.

invoice
Data type: string
Required: Yes for commercial goods, commercial samples and return shipment package contents.
The invoice number for the commercial goods or samples of package contents.

weight
Data type: integer
Required: Yes.
The total weight for all items in whole grams.

items
Data type: array of CustomsItem objects
Required: Yes.
An array containing CustomsItem objects with description for each item in the package.

7.D.2 Example

POST example a

{
  "contents": 1,
  "invoice": "1231235345345",
  "weight": 4000,
  "items": [{
  "description": "Sample Product",
    "amount": 10,
    "weight": 3000,
    "item_value": {
      "amount": 7000,
      "currency": "EUR"
    },
    "classification": "0181",
    "country": "NL"
  }, {
  "description": "Sample NBG Product",
    "amount": 5,
    "weight": 1000,
    "item_value": {
      "amount": 1000,
      "currency": "EUR"
    },
    "classification": "0181",
    "country": "BE"
  }]
}

POST example a

{
  "contents": 3,
  "invoice": "4567789004",
  "weight": 3000,
  "items": [{
    "description": "NIV Product Audio CD",
    "amount": 3,
    "weight": 1000,
    "item_value": {
      "amount": 10000,
      "currency": "EUR"
    },
    "classification": "0181",
    "country": "US"
  }, {
    "description": "Sample JP Product",
    "amount": 10,
    "weight": 2000,
    "item_value": {
      "amount": 800000,
      "currency": "YEN"
    },
    "classification": "0181",
    "country": "JP"
  }]
}

7.F CustomsItem Object Definition

7.F.1 Overview

This object contains a declaration for an item in the CustomsDeclaration object.

description
Data type: string
Required: Yes.
The description of the item.

amount
Data type: integer
Required: Yes.
The amount of this item in the package. The minimum amount is 1.

weight
Data type: integer
Required: Yes.
The total weight for these items in whole grams. Between 0 and 20000 grams.

item_value
Data type: price
Required: Yes.
Item value

classification
Data type: isic_code
Required: Yes.
The International Standard Industry Classification code for this item.

country
Data type: country_code
Required: Yes.
The country of origin for this item.

7.F.2 Example

POST example a

{
  "description": "Sample NIV Product",
  "amount": 10,
  "weight": 2000,
  "item_value": {
    "amount": 7000,
    "currency": "EUR"
  },
  "classification": "0181",
  "country": "NL"
}

POST example b

{
 "description":"Sample NBG Product",
 "amount":5,
 "weight":1000,
 "item_value":{
    "amount":1000,
    "currency":"EUR"
 },
 "classification":"0181",
 "country":"BE"
}

POST example c

{
 "description":"NIV Product Audio CD",
 "amount":3,
 "weight":1000,
 "item_value":{
    "amount":10000,
    "currency":"EUR"
 },
 "classification":"0181",
 "country":"US"
}

POST example d

{
 "description":"Sample JP Product",
 "amount":10,
 "weight":2000,
 "item_value":{
    "amount":800000,
    "currency":"YEN"
 },
 "classification":"0181",
 "country":"JP"
}

7.G ShipmentIds Object Definition

Overview

This object contains an array of ShipmentId objects.

ids
Data type: array of ShipmentId objects.
Required: n/a.
array of ShipmentId objects.

7.H ShipmentId Object Definition

Overview

id
Data type: integer
Required: n/a.
Shipment.id

7.I ReturnShipment Object Definition

7.I.1 Overview

You can create a return shipment with this object.

shop_id
Data type: integer
Required: no.
The shop id to which this shipment belongs.

parent
Data type: integer
Required: Yes.
The parent shipment that was initially sent to the consumer.

carrier
Data type: carrier
Required: Yes.
The carrier that will deliver the package.

email
Data type: string
Required: no.
The email address to send the return shipment email to.

name
Data type: string
Required: Yes.
The name to include in the email.

options
Data type: ShipmentOptions
Required: no.
The shipment options. If this is not provided then the default shop return shipment options are used.

7.I.2 Example

POST example

{
  "parent": 123456,
  "carrier": 2,
  "email": "testing@sendmyparcel.be",
  "name": "Mr. Parcel",
  "options": {
    "package_type": 1,
    "signature": 1,
    "return": 0,
    "insurance": {
      "amount": 5000,
      "currency": "EUR"
    }
  }
}

7.J UnrelatedReturnShipment Object Definition

7.J.1 Overview

You can create a unrelated return shipment with this object.

shop_id
Data type: integer
Required: No.
The shop id to which this shipment belongs.

carrier
Data type: carrier
Required: Yes.
The carrier that will deliver the package.

email
Data type: string
Required: Yes.
The email to send the return shipment email to.

name
Data type: string
Required: Yes.
The name to include in the email.

options
Data type: ShipmentOptions
Required: No.
The shipment options. If this is not provided then the default shop returnshipment options are used.

7.J.2 Example

POST example

{
  "carrier": 2,
  "email": "testing@sendmyparcel.be",
  "name": "Mr. Parcel",
  "options": {
    "package_type": 1,
    "signature": 1,
    "return": 0,
    "insurance": {
      "amount": 50,
      "currency": "EUR"
    }
  }
}

7.K DownloadUrl Object Definition

7.K.1 Overview

This is the download url object.

link
Data type: string
Required: Yes.
The url to generate an unrelated return shipment

7.K.2 Example

POST example

{
  "link": "https://backoffice.myparcel.nl/retour/8005ebb27d55425c5eaf2dff2fa41147"
}

7.L TrackTrace Object Definition

7.L.1 Overview

This is the tracktrace object.

shipment_id
Data type: integer
Required: n/a.
Shipment id.

code
Data type: string
Required: n/a.

final
Data type: boolean
Required: n/a.

description
Data type: string
Required: n/a.

time
Data type: time
Required: n/a.

history
Data type: TrackTraceHistory
Required: n/a.

7.L.2 Example

POST example

{
  "shipment_id": "1234",
  "code": "D3",
  "final": false,
  "description": "The package is in distribution",
  "time": "2015-01-02 05:00",
  "history": [{
    "code": "C3",
    "description": "The package is at the sorting center",
    "time": "2015-01-02 05:00"
    }, {
    "code": "B2",
    "description": "The package is has been scanned",
    "time": "2015-01-01 06:00"
  }]
}

7.M TrackTraceHistory Object Definition

7.M.1 Overview

This is the tracktrace history object.

code
Data type: string
Required: n/a.

description
Data type: string
Required: n/a.

time
Data type: time
Required: n/a.

7.M.2 Example

POST example

{
  "code": "C3",
  "description": "The package is at the sorting center",
  "time": "2015-01-02 05:00"
}

7.N PhysicalProperties Object Definition

7.N.1 Overview

This is the physical properties object.

carrier_height
Data type: integer
Required: n/a.

carrier_width
Data type: integer
Required: n/a.

carrier_weight
Data type: integer
Required: n/a.

carrier_length
Data type: integer
Required: n/a.

carrier_volume
Data type: integer
Required: n/a.

height
Data type: integer
Required: n/a.

width
Data type: integer
Required: n/a.

length
Data type: integer
Required: n/a.

volume
Data type: integer
Required: n/a.

weight
Data type: integer
Required: n/a.

7.N.2 Example

POST example

{
  "weight": 3000
}

7.O PickupLocation Object Definition

7.O.1 Overview

This is the pickup location object.

city
Data type: string
Required: n/a.

location_name
Data type: string
Required: n/a.

number
Data type: string
Required: n/a.

postal_code
Data type: string
Required: n/a.

street
Data type: string
Required: n/a.

location_code
Data type: string
Required: n/a.

retail_network_id
Data type: string
Required: n/a.

7.O.2 Example

POST example for BE pickup location

{
    "location_code": "207500",
    "postal_code": "1100",
    "street": "Burgemeester van Stamplein",
    "city": "Brussel",
    "number": "270",
    "location_name": "Albert Heijn"
}

7.P PaymentInstructions Object Definition

7.P.1 Overview

This is the payment instruction object.

id
Data type: string
Required: n/a.

hash
Data type: string
Required: n/a.

invoices
Data type: Invoice
Required: n/a.

type
Data type: integer
Required: n/a.

notification_hash
Data type: string
Required: n/a.

original_notification_hash
Data type: string
Required: n/a.

payment_url
Data type: string
Required: n/a.

paid
Data type: boolean
Required: n/a.

price
Data type: price
Required: n/a.

7.P.2 Example

Example

{
  "id": "93c8533d3744eaf4a24a119f068019dcfbf97551",
  "hash": "93c8533d3744eaf4a24a119f068019dcfbf97551",
  "invoices": {
    "id": 1334092,
    "number": "111704089216",
    "status": 102
  },
  "type": 1,
  "notification_hash": "27eecee49d917d9ea2700ef5ccb59d28849a8bf3",
  "original_notification_hash": "27eecee49d917d9ea2700ef5ccb59d28849a8bf3",
  "payment_url": "https://pay.multisafepay.com/pay/?transaction=25cOdyun01THR2ZpozaR5KfNPPrLCzBSFYq&lang=nl_NL",
  "paid": 0,
  "price": {
    "amount": 911,
    "currency": "EUR"
  }
}

7.Q Invoice Object Definition

7.Q.1 Overview

This is the invoice object.

id
Data type: integer
Required: n/a.

number
Data type: string
Required: n/a.

status
Data type: integer
Required: n/a.

7.Q.2 Example

Example

{
  "id": 1334092,
  "number": "111704089216",
  "status": 102
}
 

7.R ShipmentLabelDownloadLink Object Definition

7.R.1 Overview

This is the shipment label download link object.

url
Data type: string
Required: n/a.

7.R.2 Example

Example

{
  "url": "https://api.sendmyparcel.be/pdfs/461efc8b5c7e71dbd0c39a25067bda9455b0ca5a"
}

8. Delivery options

8.A Get delivery options

8.A.1 Overview

Defaults
Get the delivery options for a given location and carrier. If none of the optional parameters are specified then the following default will be used: If a request is made for the delivery options between Friday after the default cutoff_time (15h30) and Monday before the default cutoff_time (15h30) then Tuesday will be shown as the next possible delivery date.

Objects
Upon success two arrays are returned one for DeliveryOptions and one for PickupOptions objects is returned. This object contains delivery date, time and pricing. Upon error an Error object is returned.

8.A.2 Reference

{
	"data": {
		"delivery": [],
		"pickup": [],
		"message": "No results"
	},
	"errors": [{
		"code": 9,
		"message": "Example",
		"human": "Example"
	}]
}

8.A.3 Parameters

cc
Data type: country_code
Required: yes
The country code for which to fetch the delivery options. This endpoint can only be used in Belgium ( cc=BE ).

postal_code
Data type: string
Required: yes.
The postal code for which to fetch the delivery options.

number
Data type: string
Required: yes
The street number for which to fetch the delivery options.

delivery_time
Data type: time
Required: no
The time on which a package has to be delivered.
Note: This is only an indication of time the package will be delivered on the selected date.

delivery_date
Data type: date
Required: no
The date on which the package has to be delivered.

cutoff_time
Data type: time
Required: no
This option allows the Merchant to indicate the latest cut-off time before which a consumer order will still be picked, packed and dispatched on the same/first set dropoff day, taking into account the dropoff-delay. Default time is 15h30. For example, if cutoff time is 15h30, Monday is a delivery day and there's no delivery delay; all orders placed Monday before 15h30 will be dropped of at bpost on that same Monday in time for the Monday collection.

dropoff_days
Data type: weekday_digit
Required: no
This options allows the Merchant to set the days she normally goes to bpost to hand in her parcels. By default Saturday and Sunday are excluded.

saturday_delivery
Data type: boolean
Required: no
Saturday delivery is only possible when the package is delivered before 15.00 on Friday at the designated bpost locations.
Note: To activate Saturday delivery, value 6 must be given with dropoff_days, value 1 must be given by saturday_delivery.

dropoff_delay
Data type: integer
Required: no
This options allows the Merchant to set the number of days it takes her to pick, pack and hand in her parcels at bpost when ordered before the cutoff time. By default this is 0 and max is 14.

deliverydays_window
Data type: integer
Required: no
This options allows the Merchant to set the number of days into the future for which she wants to show her consumers delivery options. For example, if set to 3 in her check-out, a consumer ordering on Monday will see possible delivery options for Tuesday, Wednesday and Thursday (provided there is no drop-off delay, it's before the cut-off time and she goes to bpost on Mondays). Min is 1. and max. is 14.

exclude_delivery_type
Data type: delivery_type
Required: no
This options allows the Merchant to exclude delivery types from the available delivery options. You can specify multiple delivery types by semi-colon separating them. The standard delivery type cannot be excluded.

latitude
Data type: coordinates
Required: no
This provides the ability to display the postNL locations through the coordinates. If only latitude or longitude is passed as a parameter, it will be ignored and will simply use zip code for searching locations.

longitude
Data type: coordinates
Required: no
This provides the ability to display the postNL locations through the coordinates. If only latitude or longitude is passed as a parameter, it will be ignored and will simply use zip code for searching locations.

8.A.4 Example

Get delivery options for 2000, 16 for bpost
Request

GET https://api.sendmyparcel.be/delivery_options?cc=BEpostal_code=2000&number=16&carrier=2 HTTP/1.1
User-Agent: CustomApiCall/2

Response

HTTP/1.1 200 OK Content-Type:application/json;charset=utf-8
{
  "data": {
    "delivery": [
            {
                "date": "2018-05-17",
                "time": [
                    {
                        "start": "08:00",
                        "end": "17:00",
                        "price": {
                            "currency": "EUR",
                            "amount": 0
                        },
                        "price_comment": "standard",
                        "comment": "",
                        "type": 2
                    }
                ]
            },
            {
                "date": "2018-05-18",
                "time": [
                    {
                        "start": "08:00",
                        "end": "17:00",
                        "price": {
                            "currency": "EUR",
                            "amount": 0
                        },
                        "price_comment": "standard",
                        "comment": "",
                        "type": 2
                    }
                ]
            }
    ],
    "pickup": [
        {
            "date": "2018-05-08",
            "time": [
                {
                    "start": "16:00",
                    "type": 4,
                    "price": {
                        "amount": 0,
                        "currency": "EUR"
                    }
                }
            ],
            "location": "PRESS SH ANSELMO ANTWERPEN",
            "street": "ANSELMOSTRAAT",
            "number": "42",
            "postal_code": "2018",
            "city": "ANTWERPEN",
            "cc": "BE",
            "start_time": "11:00",
            "price": 0,
            "price_comment": "",
            "comment": "",
            "phone_number": "",
            "opening_hours": {
                "monday": [
                    "7:00 - 18:30"
                ],
                "tuesday": [
                    "7:00 - 18:30"
                ],
                "wednesday": [
                    "7:00 - 18:30"
                ],
                "thursday": [
                    "7:00 - 18:30"
                ],
                "friday": [
                    "7:00 - 18:30"
                ],
                "saturday": [
                    "7:30 - 16:00"
                ],
                "sunday": []
            },
            "distance": "894",
            "latitude": "51.2071",
            "longitude": "4.40363",
            "location_code": "822030",
            "retail_network_id": "",
            "holiday": []
        }
    ]
}

Get delivery options for 2000, 16 for bpost cutoff time 16h00, dropoff days Mon - Fri, dropoff delay is zero, delivery window is 2 days. type

Request

GET https://api.sendmyparcel.be/delivery_options?cc=BE&postal_code=2000&number=16&carrier=2&cutoff_time=16:00&dropoff_days=1;2;3;4;5;6&saturday_delivery=1&dropoff_delay=0&deliverydays_window=2&exclude_delivery_type=1  HTTP/1.1
User-Agent: CustomApiCall/2

Response

HTTP/1.1 200 OK Content-Type:application/json;charset=utf-8
[
            {
                "date": "2018-05-08",
                "time": [
                    {
                        "start": "16:00",
                        "type": 2,
                        "price": {
                            "amount": 0,
                            "currency": "EUR"
                        }
                    }
                ],
                "location": "PRESS SH ANSELMO ANTWERPEN",
                "street": "ANSELMOSTRAAT",
                "number": "42",
                "postal_code": "2018",
                "city": "ANTWERPEN",
                "cc": "BE",
                "start_time": "11:00",
                "price": 0,
                "price_comment": "",
                "comment": "",
                "phone_number": "",
                "opening_hours": {
                    "monday": [
                        "7:00 - 18:30"
                    ],
                    "tuesday": [
                        "7:00 - 18:30"
                    ],
                    "wednesday": [
                        "7:00 - 18:30"
                    ],
                    "thursday": [
                        "7:00 - 18:30"
                    ],
                    "friday": [
                        "7:00 - 18:30"
                    ],
                    "saturday": [
                        "7:30 - 16:00"
                    ],
                    "sunday": []
                },
                "distance": "894",
                "latitude": "51.2071",
                "longitude": "4.40363",
                "location_code": "822030",
                "retail_network_id": "",
                "holiday": []
            }]
}

9. Delivery options Object Definitions

If you use the endpoint delivery_options you get two objects. DeliveryOptions Object and Options Object. OpeningHours Object contains the opening hours of pickup locations.

9.A DeliveryOptions Object Definition

DeliveryOptions Object contains possible delivery options.

9.A.1 Overview

date
Data type: date
Required: n/a.

time
Data type: DeliveryOptionTime
Required: n/a.

9.A.2 Example

Example

{
  "date": "2017-02-01",
  "time": [{
    "start": "08:00",
    "end": "12:00",
    "price": {
      "currency": "EUR",
      "amount": 1000
    },
    "price_comment": "standard",
    "comment": "",
    "type": 1
    }, {
    "start": "11:30",
    "end": "13:30",
    "price": {
      "currency": "EUR",
      "amount": 0
    },
    "price_comment": "standard",
    "comment": "",
    "type": 2
    }]
}

9.B PickupOptions Object Definition

PickupOptions Object contains possible bpost locations.

9.B.1 Overview

date
Data type: date
Required: n/a.

time
Data type: PickupOptionTime
Required: n/a.

location
Data type: string
Required: n/a.

street
Data type: string
Required: n/a.

number
Data type: string
Required: n/a.

postal_code
Data type: string
Required: n/a.

start_time
Data type: time
Required: n/a.

price
Data type: integer
Required: n/a.

price_comment
Data type: string
Required: n/a.

comment
Data type: string
Required: n/a.

phone_number
Data type: string
Required: n/a.

opening_hours
Data type: string
Required: n/a.

distance
Data type: string
Required: n/a.

latitude
Data type: coordinates
Required: n/a.

longitude
Data type: coordinates
Required: n/a.

location_code
Data type: string
Required: n/a.

9.B.2 Example

Example a

{
  "date": "2017-02-01",
  "time": [],
  "location": "Staples Office Centre",
  "street": "Jacobus Spijkerdreef",
  "number": "10",
  "postal_code": "1000",
  "city": "Brussel",
  "comment": "Dit is een Business Point.",
  "opening_hours": {
    "monday": ["08:00-18:30"],
    "tuesday": ["08:00-18:30"],
    "wednesday": ["08:00-18:30"],
    "thursday": ["08:00-18:30"],
    "friday": ["08:00-18:30"],
    "saturday": ["08:00-17:00"],
    "sunday": []
  },
  "latitude": "52.286582",
  "longitude": "4.682377",
  "location_code": "173187"
}

9.C OpeningHours Object Definition

9.C.1 Overview

monday
Data type: array of string
Required: n/a.

tuesday
Data type: array of string
Required: n/a.

wednesday
Data type: array of string
Required: n/a.

thursday
Data type: array of string
Required: n/a.

friday
Data type: array of string
Required: n/a.

saterday
Data type: array of string
Required: n/a.

sunday
Data type: array of string
Required: n/a.

9.C.2 Example

Example

{
  "monday": ["08:00-18:30"],
  "tuesday": ["08:00-18:30"],
  "wednesday": ["08:00-18:30"],
  "thursday": ["08:00-18:30"],
  "friday": ["08:00-18:30"],
  "saturday": ["08:00-17:00"],
  "sunday": []
}

9.D DeliveryOptionTime Object Definition

9.D.1 Overview

start
Data type: time
Required: n/a.

end
Data type: time
Required: n/a.

price
Data type: price
Required: n/a.

price_comment
Data type: string
Required: n/a.

comment
Data type: string
Required: n/a.

type
Data type: integer
Required: n/a.

9.D.2 Example

Example

{
  "start": "08:00",
  "end": "12:00",
  "price": {
    "currency": "EUR",
    "amount": 1000
  },
  "price_comment": "standard",
  "comment": "",
  "type": 1
}

9.E PickupOptionTime Object Definition

9.E.1 Overview

start
Data type: time
Required: n/a.

type
Data type: integer
Required: n/a.

price
Data type: price
Required: n/a.

9.E.2 Example

Example

{
  "start": "16:00",
  "type": 4,
  "price": {
    "amount": 0,
    "currency": "EUR"
  }
}

10. Webhooks

10.A Add subscription

10.A.1 Overview

Use this endpoint to subscribe to an event in our API. Upon success a HTTP/1.1 200 OK with subscription ids is returned. You must use HTTPS for callback because it's secure and temper proof. Adding the same webhook overwrites the existing one. Tip: You can test webhooks with Webhook Tester

10.A.2 Reference

10.A.3 Example

Request

POST https://api.sendmyparcel.be/webhook_subscriptions HTTP/1.1
User-Agent: CustomApiCall/2
Authorization:basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==
Content-Type:application/json; charset=utf-8
{
  "data": {
    "webhook_subscriptions": [{
      "hook": "shipment_status_change",
      "url": "https://seoshop.nl/myparcel/notifications"
    }]
  }
}

Response

HTTP/1.1 200 OK Content-Type:application/json; charset=utf-8
{
  "data": {
    "ids": [{
      "id": 3
    }]
  }
}

10.B Delete subscription

10.B.1 Overview

Use this endpoint to delete webhook subscriptions. You can specify multiple subscription ids by semi-colon separating them on the URI. Upon delete an HTTP/1.1 204 No Content is returned.

10.B.2 Reference

10.C.3 Parameters

id
Data type: integer.id
The id of the subscription to delete. You can specify multiple subscriptions by semi-colon separating them.

10.B.4 Example

Request

DELETE https://api.sendmyparcel.be/webhook_subscriptions/1 HTTP/1.1
User-Agent: CustomApiCall/2
Authorization:basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==

Response

HTTP/1.1 204 No Content

10.C Get subscription

10.C.1 Overview

Use this endpoint to fetch webhook subscriptions. You can specify multiple subscription ids by semi-colon separating them on the URI. Upon success a HTTP/1.1 200 with an array of Subscription objects is returned.

10.C.2 Reference

10.C.3 Parameters

id
Data type: integer
This is the subscription id. You can specify multiple subscription ids by semi-colon separating them on the URI.

10.C.4 Example

Request

GET https://api.sendmyparcel.be/webhook_subscriptions/12 HTTP/1.1
User-Agent: CustomApiCall/2
Authorization: basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==

Response

HTTP/1.1 200 OK Content-Type:application/json;charset=utf-8
{
  "data": {
    "webhook_subscriptions": [{
      "id": 123,
      "hook": "shipment_status_change",
      "url": "https://seoshop.nl/myparcel/notifications"
    }]
  }
}

11. Webhook Object Definitions

11.A Subscription Object Definition

11.A.1 Overview

This object contains an event and a callback URL that will receive notifications.

id
Data type: integer
Required: No.
The id of the webhook subscription.

hook
Data type: string
Required: Yes.
The event from which you want to receive notifications.

url
Data type: string
Required: Yes.
The callback URL on which to receive notifications. The URL must be https.

account_id
Data type: integer
Required: No.
The account id to which this subscription belongs.

shop_id
Data type: integer
Required: No.
The shop id to which this subscription belongs.

11.A.2 Example

POST Example

{
   "hook":"shipment_status_change",
   "url":"https://seoshop.nl/myparcel/notifications"
}

GET Example

{
  "id": 123,
  "account_id": 1,
  "shop_id": 2,
  "hook": "shipment_status_change",
  "url": "https://seoshop.nl/myparcel/notifications"
}

11.B ShipmentStatusChangeEvent Object Definition

11.B.1 Overview

This object contains the shipment status change event. This object is sent to the callback URL specified in the Subscription object whenever a shipment status changes.

shipment_id
This is the shipment id.

account_id
This is the account id to which the shipment belongs.

shop_id
This is the shop to which the shipment belongs.

status
The shipment status.

barcode
This is the shipment barcode.

11.B.2 Example

Example a

{
  "data": {
    "hooks": [
      {
        "shipment_id":"25482412",
        "account_id":7003,
        "shop_id":1897,
	"status":2,
	"barcode":"3SMYPA749883621"
      },
      {
        "shipment_id":25482412,
	"account_id":7003,
	"shop_id":1897,
	"status":2,
	"barcode":"3SMYPA749883620"
      }
    ]
  }
}

11.C SubscriptionIds Object Definition

Overview

This object contains an array of SubscriptionId objects.

ids
Data type: array of SubscriptionId objects.
Required: n/a.
array of SubscriptionId objects.

11.D SubscriptionId Object Definition

Overview

id
Data type: integer
Required: n/a.
Subscription.id

12. Document changes

Click here for the latest version of the API documentation. Last version update is done on .