api

Document structure

address object attributes

Name Description Type Format Restrictions Maximum length
name Name string Basic Latin string with no special characters (¹) required 35
address1 Address string Basic Latin string with no special characters (¹) required 30
address2 Address string Basic Latin string with no special characters (¹) optional 30
city City string Basic Latin string with no special characters (¹) required 30
postalCode Postal code string   required 30
state State / province string 2 letter ISO Alpha-2 code required (⁴) 20
country Country string 2 letter ISO Alpha-2 code required 2
contact Contact name string Basic Latin string with no special characters (¹) required 35
phone Contact phone number number (⁹)(²)(³) optional 25
email Contact email string   required (⁵) 50
isResidential Address is not for a company boolean   optional  
taxIdentification Tax / VAT number string Basic Latin string with no special characters (¹) optional (*) 45

(*) taxIdentification is only required for sender address in international shipments with starting point “IT” and carrier FEDEX.

amount object attributes

Name Description Type Format Restrictions
amount Amount value number (³)(⁶) required
currency Amount currency string Currently the only accepted value is “EUR” required

dimensions object attributes

Name Description Type Format Restrictions
length Package length number (³)(⁶) required
width Package width number (³)(⁶) required
height Package height number (³)(⁶) required
units Dimensions units number Currently the only accepted value is 1, for “KG” required

documents object attributes

Name Description Type Format
contentType Content-Type MIME Header string type/subtype
fileName Name of the file string  
fileData Body of the file, encoded using the Base64 scheme string  

exportDeclaration object attributes

Name Description Type Format Restrictions
exportReasonType Reason for export. string (*) required
invoiceDate Date of invoice. string ISO 8601 Date required
invoiceReference Invoice reference. string   required
invoiceFreight Invoice freight. amount object   optional
shipmentPurpose Shipment purpose. string (**) required
lineItems One or more lineItem objects. lineItem object   required

(*) possible values:

(**) possible values:

lineItem object attributes

Name Description Type Format Restrictions
reference Item reference. string   required
productId Product Id string   required
description Description string   required
quantity Quantity number (³)(⁶) required
unitPrice Unit price number (³)(⁶) required
originCountry Origin country. string   required
commodityCode HS Code string   required
unitWeight Unit weight number (³)(⁶) required

package object attributes

Name Description Type Format Restrictions
weight Package weight weight object   required
dimensions Package dimensions dimensions object   required
type Package type string Accepted values: ‘CARTON’, ‘PALLET’ required

rate object attributes

Name Type Notes
type string required
id string required
attributes object required
attributes.carrierCode string required
attributes.carrierName string required
attributes.serviceCode string required
attributes.serviceName string required
attributes.serviceDefinitionCode string required
attributes.accountId string required
attributes.finalCost amount required
attributes.estimatedDeliveryDate string optional; ISO 8601 Date; nullable

shipment object attributes

Name Description Type Format Restrictions Default
shipDate Departure date string ISO 8601 Date optional (**)  
shipFrom Sender address address object   required  
collectionLocation Collection location address object   optional  
shipTo Receiver address address object   required  
packages One or more package objects package object   required (*)  
goodsDescription Description of items being shipped string   required  
insuranceDescription Detailed description of insured items string   optional (**)  
insuranceValue Insured amount. number (³)(⁶) optional (**)  
invoiceSubtotal Value of items being shipped number (³)(⁶) required  
customerReference Customer reference (free text) string   optional  
specialInstructions Special instructions for carrier string   optional  
confirmationEmail Send confirmation with labels to this address string   optional  
booking Use collection booking boolean true, false optional true
documentsOnly Ship documents instead of goods. boolean true, false optional (^) false

(*) except for the /shipments/save endpoint, where packages can be omitted;

(**) insurance is optional, however if one field is filled then the other must also be filled; Currently the insurance rate is NOT included in the A.P.I. rating, but if this is requested (by filling in the goods description and value fields) it will be invoiced at the end of the month according to the agreed rates; you can check the costs of the insurance policy with the ParcelValue Customer Service by writing to info@parcelvalue.eu

(**) if shipDate is omitted, it will be managed by the system;

(^) documentsOnly restrictions:

shipment object meta

Name Description Type Format Restrictions
carrierChoice Carrier Choice (request) string DHL, POSTE_ITALIANE, TNT, UPS Optional, used in “one-step” endpoint
carrierName Carrier name string   response only (⁷)
finalCost Final shipment cost amount object   response only (⁷)
insuranceCost Insurance finalCost amount object   response only (⁷)
rate Shipment rate to use when confirming rate object   required for confirm endpoint
reference Reference number (used in the Client area) string   response only (⁷)
scheduledProcessing Scheduled processing option boolean true, false (*)
service Shipment service choice (request) string express, economy required for “one-step” endpoint
status Shipment status code integer -1, 0, 3 response only
trackingNumber Tracking number string   response only (⁷)

(*) scheduledProcessing

Used only in the “one-step” endpoint;

true
false

Shipment status codes

Code Description
-1 Error
0 Saved (pending confirmation)
3 Shipment is confirmed
Name Description Type Format Restrictions
self Shipment resource URL string <apiURL>/shipments<id> response only
tracking External tracking URL string   response only (⁸)

tracking object attributes

Name Description Type
carrierShipmentId Tracking number string
trackingHash Tracking hash code (*) string
trackingStatus Status of latest tracking event (**) integer (nullable)
trackingDate Date and time of latest tracking event string (nullable)

(*) trackingHash

The hash code can be used to generate the tracking link. The format is: https://tracking.qapla.it/<trackingHash>.

(**) trackingStatus

For complete information about the tracking status code please see Qapla’ documentation.

weight object attributes

Name Description Type Format Restrictions
value Weight value number (³)(⁶) required
units Weight units number Currently the only accepted value is 1, for “KG” required

Notes

(¹) Data containing special characters will be converted;

(²) For US, phone should start with 1 and contain 11 digits;

(³) Numbers containing non-numeric characters will be rejected; Please make sure to use the point (.) as decimal separator;

(⁴) state is required only for the following countries: IT, CA, US;

(⁵) email is required for the shipFrom address;

(⁶) Any value using a fractional part must use a period as the decimal separator;

(⁷) This field is only returned for completed shipments, otherwise the value is null;

(⁸) This field is only returned for completed shipments, otherwise the field is not present in the response;

(⁹) Non numeric values will be discarded.

README

This site is open source. Improve this page.