API documentation Parcels

Contents

• Get parcel information
  • Attributes
  • Example
• Create parcel
  • Attributes
  • Example: create regular parcel
  • Example: create bulk parcel
  • Example: create flat parcel without delivery
  • Example: create flat parcel with declaration and delivery
• Update parcel
  • Attributes
  • Example: assign waybill
  • Example: unassign waybill
• Add attachments
  • Attributes
  • Example

Get parcel information

Provides all available information about a parcel.

Endpoint

[GET] /v4/parcels/{client_ref}

Attributes

Key	Description	Datatype	Constraints/Remarks
ref	ViaEurope reference of parcel	String	Always 'VIA-', followed by a unique combination of 8 letters and numbers
client_ref	Client reference of parcel	String	5-30 characters, must only contain characters A-Z, 0-9, minus and underscore
order_client_ref	Client reference of order	String	5-30 characters, must only contain characters A-Z, 0-9, minus and underscore
barcode	Barcode of parcel	String
state	State of parcel	String	Can be pending parcel has not arrived at eHub yet at_ehub parcel is at our eHub, but not ready to be handed over handed_over parcel is handed over to the courier and has left our eHub
first_ehub_scan_at	Timestamp of parcel's first scan at our eHub	Timestamp
most_recent_ehub_scan_at	Timestamp of parcel's most recent scan at our eHub	Timestamp
type	Type of parcel	String	See create attributes for a description of parcel types
packaging_type	Packaging Type of parcel	String	See create attributes for a description of parcel types
ehub_scan_weight	Parcel weight, determined by scale in our eHub, in grams	Integer
ehub_scan_dimensions	Parcel dimensions, determined by measuring device in our eHub, in cm	Array of integers

Example

Response

{
  "ref": "VIA-G0000000",
  "client_ref": "CLIENTREF-001",
  "order_client_ref": "ORDER-123",
  "barcode": "1Z97V8800000000000",
  "state": "handed_over",
  "first_ehub_scan_at": "2018-11-04 15:47:37 +0100",
  "most_recent_ehub_scan_at": "2018-11-04 15:56:05 +0100",
  "type": "regular",
  "ehub_scan_weight": 18500,
  "ehub_scan_dimensions": [
    63,
    54,
    39
  ]
}

Create Parcel

Creates a new parcel in the ViaEurope system. This endpoint has no response, other than a HTTP status code to indicate success or failure, along with possible errors.

Endpoint

[POST] /v4/parcels

Attributes

Key	Description	Datatype	Constraints/Remarks	Error messages
client_ref	Client reference of parcel	String	5-30 characters, must only contain characters A-Z, 0-9, minus and underscore	Client ref is too short (minimum is 5 characters) Client ref is too long (maximum is 30 characters) Client ref has already been taken Client ref must only contain characters A-Z, 0-9, minus and underscore
barcode	Barcode of parcel	String	5-50 characters, must be unique, must be provided if no delivery is booked through ViaEurope	Barcode can't be blank (for flat parcels, if no declarations submitted) Barcode can't be set (for regular and bulk parcels, if no declarations submitted) Barcode is too short (minimum is 5 characters) Barcode is too long (maximum is 50 characters) Barcode has already been taken
type	Type of parcel	String	Can be regular (normal parcel), bulk (bulk parcel), or flat (flat/small parcel contained in bulk parcel)	Type can't be blank Type has an invalid value
packaging_type	Packaging Type of parcel (only for bulk type parcels)	String	Can be bag, box gaylord	Packing Type can't be blank Packaging Type has an invalid value
order_client_ref	Client reference of order	String	5-30 characters, must only contain characters A-Z, 0-9, minus and underscore	Order client ref is too short (minimum is 5 characters) Order client ref is too long (maximum is 30 characters) Order client ref must only contain characters A-Z, 0-9, minus and underscore
waybill_client_ref	Client reference of waybill	String		Waybill client ref is unknown
bulk_parcel_client_ref	Client reference of bulk parcel containing this parcel. Can only be used with "type"="flat"	String		Bulk parcel client ref is unknown Bulk parcel must be blank (if type isn't 'flat')
expected_flat_parcels_count	Number of flat parcels assigned to this bulk parcel.	Integer	Only for parcels of type bulk . This field is optional.	Expected flat parcels count is not a number
inspected_by_client	Indicates whether client performed an inspection before sending off the parcel	Boolean
handed_over_by_client_at	Time of handover from client to transportation company at origin.	ISO8601
declaration	Attributes for the declaration of this parcel, see here	JSON		Declarations must be blank (if type is 'bulk')
delivery	Attributes for the delivery of this parcel, see here	JSON

Example: Create regular parcel

Request

{
  "type": "regular",
  "client_ref": "CLIENT123",
  "order_client_ref": "ORDER123",
  "inspected_by_client": true,
  "handed_over_by_client_at": "2018-10-08T13:20:55+02:00",
  "waybill_client_ref": "180-12345675",
  "delivery": {
    "address": {
      "name1": "Mr Appleseed",
      "street": "Example Street 1",
      "city": "Example City",
      "zip": "10001",
      "country": "DE",
      "phone": "0049123456"
    },
    "service": "UPS_BE_MULTI",
    "weight": 11000,
    "dimensions": [
      30,
      20,
      45
    ]
  },
  "declaration": {
    "type": "sale_b2c_4",
    "country_of_export": "CN",
    "origin_client_ref": "FOOBAR",
    "declaration_country": "NL",
    "consignee": {
      "name1": "Mr Appleseed",
      "street": "Example Street 1",
      "city": "Example City",
      "zip": "12345",
      "country": "FR",
      "phone": "0044123456"
    },
    "products": [
      {
        "description": "Beard Trimmer",
        "taric": "1234567890",
        "base_value": 17990,
        "quantity": 10,
        "weight": 10000,
        "country_of_origin": "CN",
        "marketplace_url": "https://www.amazon.co.uk/dp/B07BHXZLZR"
      },
      {
        "description": "Ballpoint Pen",
        "taric": "1234567890",
        "base_value": 1400,
        "quantity": 150,
        "weight": 1000,
        "country_of_origin": "CN",
        "marketplace_url": "https://www.amazon.co.uk/dp/B000I5ZK2U"
      }
    ]
  }
}

Example: Create bulk parcel

Request

{
  "type": "bulk",
  "packaging_type": "gaylord",
  "client_ref": "BULK123",
  "waybill_client_ref": "180-12345675",
  "expected_flat_parcels_count": 69,
  "delivery": {
    "address": {
      "name1": "Mr Appleseed",
      "shortcode": "DE44145",
      "phone": "0044123456"
    },
    "service": "BEX",
    "weight": 10000,
    "dimensions": [
      10,
      20,
      30
    ]
  }
}

Example: Create flat parcel with declaration

Request

{
  "type": "flat",
  "barcode": "123456",
  "client_ref": "CLIENT123",
  "bulk_parcel_client_ref": "BULK123",
  "declaration": {
    "consignee": {
      "name1": "ViaEurope BV",
      "street": "Pudongweg 21",
      "zip": "1437EM",
      "country": "NL",
      "city": "Rozenburg"
    },
    "type": "sale_b2c_4",
    "origin_client_ref": "FOOBAR",
    "country_of_export": "CN",
    "declaration_country": "NL",
    "ioss_number": "VIAIOSS-11AA22BB",
    "products": [
      {
        "description": "Carpenter Hammer",
        "taric": "1234567890",
        "base_value": 1199,
        "quantity": 10,
        "weight": 1500,
        "country_of_origin": "CN",
        "marketplace_url": "http://www.amazon.de",
        "client_ref": "XIYAR123"
      }
    ]
  }
}

Update Parcel

Updates a parcel, identified by its client_ref. You must only send attributes along that you wish to update. Only a subset of the create attributes is allowed here. This endpoint has no response, other than a HTTP status code to indicate success or failure, along with possible errors.

Endpoint

[PATCH] /v4/parcels/{client_ref}

Attributes

Key	Description	Datatype	Constraints/Remarks
waybill_client_ref	Client reference of waybill	String
bulk_parcel_client_ref	Client reference of bulk parcel containing this parcel.	String	Can only be used for flat parcels.
order_client_ref	Client reference of order	String	5-30 characters, must only contain characters A-Z, 0-9, minus and underscore	Order client ref is too short (minimum is 5 characters) Order client ref is too long (maximum is 30 characters) Order client ref must only contain characters A-Z, 0-9, minus and underscore
inspected_by_client	Indicates whether client performed an inspection before sending off the parcel	Boolean
handed_over_by_client_at	Time of handover from client to transportation company at origin.	ISO8601

Example: assign parcel to waybill

Request

{
  "waybill_client_ref": "HKG-180415-01"
}

Example: unassign parcel from waybill

Request

{
  "waybill_client_ref": null
}

Add attachments

Endpoint

[POST] /v4/parcels/{client_ref}/attachments

Attributes

Key	Description	Datatype	Constraints	Errors
type	The type of attachment to be uploaded.	String	Required, can be atr	Type can't be blank Type is not valid
filename	Name under which the document will be saved.	String	Required, /[a-z0-9\. -_]+\.(pdf|xls|xlsx)/i must include file extension, lower and upper case characters are allowed	Filename can't be blank Filename is not acceptable
attachment_base64	Base64-encoded (compatible with RFC 4648) content of the attachment.	String	See below	Attachment can't be blank Attachment size must be between 1KB and 1MB

Attachment file

In order to include your attachment file in JSON, follow these steps:

• Make sure your attachment file is in PDF or Excel format; otherwise convert it to PDF first
• Make sure your attachment file is not larger than 1MB; otherwise, compress first
• Base64-encode (compatible with RFC 4648) your attachment file
• The result of this encoding is the value of the attachment_base64 attribute
• You may add multiple attachments of each type to a Parcel, but you can upload only one document per request.

Example (add attachment to parcel)

{
  "type": "atr",
  "filename": "atr.pdf",
  "attachment_base64": "JVBERi0xLjQKJeTjz9IKMSAwIG9iag…"
}