Request

Endpoints

key	value
endpoint	platform.packaly.com/api/v1/shipmetns/manifests
method	POST

Headers

name	value	required
API-Key	the key	yes
Correlation-Id	uuid v4	no

Body

a JSON array of shipments:

name	type	description	required
reference_id	string	unique delivery id (barcode)	yes
dropoff.name	string	recipient name	yes
dropoff.email	string	recipient email	yes
dropoff.location.country	string	destination country alpha 2 code ISO 3166	yes
dropoff.location.city	string	destination city	yes
dropoff.location.postal_code	string	destination postal code as PC6 (DDDD LL)	yes
dropoff.location.street	string	destination street	yes
dropoff.location.house	string	destination house number	yes
package.height	int	parcel height in centimetres	yes
package.width	int	parcel width in centimetres	yes
package.length	int	parcel length in centimetres	yes
package.weight	int	parcel weight in grams	yes

example of a JSON request body

[
    {
        "reference_id": "53",
        "dropoff": {
            "name": "name",
            "email": "[email protected]",
            "location": {
                "country": "NL",
                "city": "city",
                "postal_code": "postal_code",
                "street": "street",
                "house": "house"
            }
        },
        "package": {
            "height": 1,
            "width": 1,
            "length": 1,
            "weight": 1
        }
    }
]

whole request as CURL:

curl --location '0.0.0.0:80/api/v1/shipments/manifests' \
--header 'API-Key: pactest_***_***' \
--header 'Correlation-Id: c2067b12-f6c3-47cf-9f98-14ea1d126100' \
--header 'Content-Type: application/json' \
--data-raw '[
    {
        "reference_id": "53",
        "dropoff": {
            "name": "name",
            "email": "[email protected]",
            "location": {
                "country": "NL",
                "city": "city",
                "postal_code": "postal_code",
                "street": "street",
                "house": "house"
            }
        },
        "package": {
            "height": 1,
            "width": 1,
            "length": 1,
            "weight": 1
        }
    }
]'

Response

On Success

HTTP code	HTTP status	HTTP body
201	CREATED	<empty>

next step is to wait from us for a webhook update with the shipment status.

On Failure

Body

a JSON error object

name	type	description	required
code	enum	error code	yes
description	string	human readable error description	yes

possible error codes:

name	description
authentication_error	request authentication failed, check error description for details.
bad_request	request body is malformed or does not contain a valid JSON (an array of shipments).
internal_server_error	we work hard to make sure that this error is never seen. But in case it is - please retry the request.

example of an error response:

{
    "code": "authentication_error",
    "description": "provided API key is not in the correct format or has been tampered with"
}

error status codes:

status code	error code	advice
401 Unauthorised	authentication_error	is request header 'API-Key' sent? is correct api key is used? was api key revoked? does api provide sufficient authorisation level?
400 Bad Request	bad_request	is request body sent? is request body a valid JSON (and array of shipments)?
500 Internal Server Error	internal_server_error	sorry, please retry.