API documentation Shipment creation

Contents

Create Waybill With Prealert Request

Creates a new request that will create waybill, bulk parcel and all the parcels. This request expects a zip file to be sent in the body of the request, no other data is required. This endpoint has no response, other than a HTTP status code to indicate success or failure, along with possible errors.

Endpoint

[POST] /v4/shipments

curl example

curl -X POST -H "Content-Type: application/zip" -H "AUTHORIZATION: Token token=api_key" -H "Accept: application/json" -i -F "file=./path/to/file.zip" app.viaeurope.com/api/v4/shipments

Attributes

Zip file with all the contents required in the body of the request. Expected file name pattern is {client_ref}_prealert.zip

Possible errors on zip file

Below described are the files required in the zip file. Please note that {client_ref} needs to be consistent all through the file names and the data in the files.

File Description Expected file name pattern File type Errors
Waybill data waybill json attributes "{client_ref}_waybill.json" JSON
  • File must include _waybill.json
Manifest Make sure your manifest file is in PDF format; otherwise convert it to PDF first Make sure you manifest file is not larger than 2MB; otherwise, compress first "{client_ref}_manifest.pdf" PDF
  • File must include _manifest.pdf
Packing list Packing list csv columns "{client_ref}_packing_list.csv" CSV
  • File must include _packing_list.csv

Waybill JSON attributes

Key Description Datatype Constraints
carrier_ref Official reference (MAWB/BoL) from carrier String Required
[A-Z-_]{5,15}
IATA-format for air waybills
client_ref Reference of your choice String Required
Unique
[A-Z-_]{5,30}
consignor_address_attributes Address of the waybill's consignor JSON Check here for a description of consignor attributes
consigned_to_ehub Waybill consignee ehub. Possible values: LGG, AMS, BUD, FRA String Required
delivery_type Can be delivered or picked_up String Required.
Must be delivered if waybill type road
expected_ground_handler Ground Handler expected to handle the waybill String Optional. Allowed values depend on the consigned_to_ehub ( Click here to see how to get a full list of available ground handlers ).
flight_departure_airport Departure airport IATA code String Required,
if flight_ptd is submitted
flight_departure_scheduled_on, Scheduled departure date in local timezone: YYYY-MM-DD String Optional
flight_number Should be two letters followed by 3 or 4 alphanumeric characters. String Optional,
if no other flight param is submitted
load_type Can be uld or loose or pallets String Optional.
delivery_type must be delivered.
port_of_arrival For waybill type air possible values are AMS, BLL, BRU, BUD, CDG, CGN, FRA, HEL, HHN, LEJ, LGG, LUX, MAD, MST, MUC, MXP, OSL, OST, PRG, VIE, WAW and XCR .
For waybill type sea possible values are ANR, RTM and ZEE .
For waybill type rail possible values are CGN, DUI, HEE, LGG, MLW, NUS and TLB . 		String Required, unless type road. [a-zA-Z]{3}
processing_ehub Key of processing EHub. Possible values: LGG, AMS, BUD, FRA String Optional. If not provided, will be equal to AMS.
uld_count Number of ULDs for waybill Integer Optional
greater than or equal to 0
⚠️ Deprecated!
This field is deprecated and won't have any effect on the waybill. Please use uld_refs field instead.
uld_refs Reference numbers of the ULDs for waybill Array of hashes Optional
  • Array of hashes with reference numbers for this waybill.
    The reference numbers shall be unique for this waybill.
    Example: [{ ref_number: "PMC12345AA" }, { ref_number: "PMC12345AB" }]
  • Reference numbers must have format: 3 letters, 4-5 numbers, 2-3 letters/numbers, no spaces. Example: PMC12345AB.
units As written on manifest Integer Required
1-10000
vol_weight In grams
As written on manifest		 Integer Required
1000-30000000
1000-10000000 for air waybills

Consignor attributes

Key Description Datatype Constraints Errors
name1 Name String Maximum 35 characters. Must only contain latin or printable ASCII characters. Must not contain line breaks.
  • Name1 can't be blank
  • Name1 is too long (maximum is 35 characters)
  • Name1 must only contain latin or printable ASCII characters
  • Name1 must not contain multiple lines
name2 Name (continued) String Optional. Maximum 35 characters. Must only contain latin or printable ASCII characters. Must not contain line breaks.
  • Name2 must only contain latin or printable ASCII characters
  • Name2 is too long (maximum is 35 characters)
  • Name2 must not contain multiple lines
street Street String Maximum 70 characters. Must only contain latin or printable ASCII characters. Must not contain line breaks. Must not contain zip code. Must not contain city.
  • Street can't be blank
  • Street is too long (maximum is 70 characters)
  • Street must not contain city, building, or company name
  • Street must only contain latin or printable ASCII characters
  • Street must not contain multiple lines
city City String 2-35 characters. Must only contain latin or printable ASCII characters. Must not contain line breaks.
  • City can't be blank
  • City is too short (minimum is 2 characters)
  • City is too long (maximum is 35 characters)
  • City must only contain latin or printable ASCII characters
  • City must not contain multiple lines
country Country String 2 character ISO 3166-Alpha 2 country code.
  • Country can't be blank
  • Country is unknown or not supported
  • Country is invalid
  • Country must be an ISO 3166-2 code, one of AU, GB, CN, HK, IN, LK, TR, US
zip Zip String Zipcode associated with the address
  • ZIP can't be blank
  • ZIP has invalid format (country-specific)
email Email of recipient String Optional. Maximum 50 characters
  • Email can't be blank
  • Email is not a valid email address
  • Email is too long (maximum is 50 characters)
phone Phone number String Optional. Maximum 15 characters. Must only contain characters 0-9, plus and minus.
  • Phone can't be blank
  • Phone must only contain characters 0-9, plus and minus
  • Phone is too long (maximum is 25 characters)

Packing list CSV columns

Key Required Description Type Format Example
client_ref required Your own parcel reference number String Min 5, Max 30 characters, uppercase 5 <= n <= 30 /\A[A-Z0-9\-_]*\z/ BG2307313115743
barcode required The parcel barcode String Min 5, Max 30 characters, uppercase 5 <= n <= 50 /\A[A-Z0-9\-_]*\z/ 158272700163987803609200
bulk_parcel_client_ref required Your reference or barcode of the bulk parcel String Min 5, Max 30 characters, uppercase 5 <= n <= 30 /\A[A-Z0-9\-_]*\z/ 6OJ2308010000112
mawb required The shipment’s Air Waybill IATA number String /[A-Z-_]{5,15}/ 235-28143076
name1 required Declaration consignee name String max 35 characters, /^.{1,35}$/ Stephen Segal
name2 optional Declaration consignee name (continuation) String max 35 characters, /^.{1,35}$/
street required Declaration consignee address street name String Max 70 characters, must not contain zip code or city Hauptstrasse 27
zip required Declaration consignee address postal code String Must match country postcode format 10827
city required Declaration consignee address city String Min 2, max 35 characters, /^.{2,35}$/ Berlin
country required Declaration consignee address country ISO 3166–2 code String /[A-Z]{2}/ DE
email required Declaration consignee email String A valid email address example@qq.com
phone required Declaration consignee phone String /\A[+0-9-]+\z/ +49415926535, 00492345678901
shipping_cost optional Product shipping cost in Euro cents Integer 100 <= n <= 10000 450
description required Product description String Women's Pants
quantity required Product quantity Integer Min 1, Max 15000, 1 <= n <= 15000 2
weight required Product weight in grams Integer Min 1g, Max 30kg, 1 <= n <= 30000 450
price required Product price in Euro cents (intrinsic value) Integer Min 1 cent, Max 100,000.00 EUR, 1 <= n <= 10000000 343
hs_code required Product hs (taric) code String Valid HS code 6211490000
country_of_origin required Product’s country of origin. String Enum:[AU,GB,CN,IN,LK,TR,US], /[A-Z]{2}/ CN
websiteurl optional Marketplace URL with verifiable information about the product String Valid marketplace URL https://de.shein.com/...
origin_ref optional Your given reference number for this parcel’s declaration String Min 5, Max 30 characters, uppercase 5 <= n <= 30 /\A[A-Z0-9\-_]*\z/ BG2307313115743
vat_number optional VAT number for the declaration, must be approved by ViaEurope String A valid and accepted VAT number DE123456789
poa_number optional Power of Attourney reference, must be approved by ViaEurope String A valid and accepted POA number 654321
ioss_number optional IOSS number, must be approved by ViaEurope String A valid and accepted IOSS number IM0123456789
destination_shortcode optional destination shortcode, must be approved by ViaEurope String A valid ViaEurope shortcode DEST-123 
 /^(?>(\p{latin}|[\u0020-\u007E]))*$/
...;name1;name2;street;....
...;Harry Potter;;Hogwarts Avenue 12;....