Dashboard

Easy Parcel API system enables access through specific calls to the shipping estimate calculation engine, facilitating subsequent finalization of orders.

While all code examples are presented in PHP, it is feasible to develop these calls in any language and environment. For Windows, you can refer to the following page: https://stackoverflow.com/questions/4015324/how-to-make-http-post-web-request.

Last version: 1.1.20

History

This section contains the changelog of the

Versions Table

Version Date Description
2024-06-14 Improvements applied to the quotation API call to return the availability mode of the cash on delivery service in the servizi field. The letter C means CASH while the letter A means BANK CHECK TO THE SENDER.
Apply the same improvements to the order API call which allows specifying the requested cash on delivery service mode in the contrassegno_modalita field by indicating C for CASH or A for BANK CHECK TO THE SENDER. A check is provided on the indicated value, if compatible with the result of the quotation.
2024-06-12 Updated the order-fast API call to returns the global base64 encoded PDF and the consignment note number and the related single base64 encoded PDF for each package.
2024-06-07 Updated the getwaybill API call to add the single_waybills field in the call. If set to Y, it returns the consignment note number and the related single base64 encoded PDF for each package.
2024-05-17 Updated the answer of the tracking API call with the addition of the firma field which contains the name of who received and signed the shipment.
2024-04-12 Updated the order API call with the addition of the destinatario->codicefiscale field required for foreign shipments.
2024-01-25 Added new API call order-fast which, with a single call, makes a "quotation," followed by an "order," and then a "getwaybill," directly returning the produced waybill, also in Base64 format.
Also added is the new API call getwaybill that returns the waybill, also in Base64, of a specific order.
2023-10-20 Updated the quotation API call which now also returns the availability mode of the cash on delivery service in the new servizi field. The letter C means CASH while the letter A means BANK CHECK TO THE SENDER.
2023-10-17 Updated the getorder response with the addition of the contrassegno_modalita field reporting "C" for cash and "A" for check.
2023-02-08 Updated the response to the getorder request with the addition of the url_bordero field that returns the URL where to download the border to be delivered to the driver picking up the shipment.
2022-08-31 Updated the response to the order request with the addition of the id_ordine field, which shows the numeric ID of the newly created order.
2022-07-14 Updated the listorder request with the addition of pagination. It is now possible to pass 2 new data: paginazione for pagination, which defines the size of the returned list (default 10, max. 100) and pagina for page, which identifies the page to be displayed (default 1). The display order has also been reversed, from newest to oldest.
In the response, the global number of orders, the pagination value and the returned page are returned respectively.
2022-06-29 Updated the listorder request with the addition of the new filter field idcustomer to obtain the order list of the individual user. Package details with measurements and weights have also been added to the response.
2022-05-13 Error 132 added in order request for carriers that cannot be purchased via API.
2022-04-14 Updated the explanation of the newcustom request with a more correct description of mandatory and/or optional fields.
2021-09-16 Updated the quotation request by adding shipment_type = I (import) and shipment_thing = P (pallets).
Updated the order request which now accepts the coupon parameter for applying discounts in special campaigns.
Updated the tracking request that now also accepts the waybill number (ldv) as a parameter.
Added the new checkcoupon request that allows you to check the correctness and validity of the coupon.
2021-02-18 Updated the quotation request with the addition of the maximum limit for marking and insurance.
2021-02-17 Updated the order request with the addition of the shipment pickup request fields.
Updated the getorder response with the addition of the field codice_ritiro (collection code), if requested.
2021-01-25 Added the following requests: newcustomer, addfund and balance.
2020-05-25 Updated the response of getorder request by adding the fields nome_vettore and logo_vettore that contains the name of the carrier and its logo, respectively.
2020-05-21 Updated the response of the tracking request with the addition og the field codice_prenotazione (reservation code), which will be filled in only in the case of a pickup request and only when actually launched by the automated systems.
2020-04-23 Updated the response of the quotation request to conform to the others. The optional version Updated the quotation call response to conform to the others. The optional version field has been added to force a response in a given version. If there is none, the response will be provided based on the version of the APIKEY activated. To request an APIKEY version update, please contact us.
2020-03-31 Added new GetOrder, ListOrder and Tracking requests.
2019-12-01 First revision of the API system.

ApiKeyInfo

The apikeyinfo request allows you to get some information about your ApiKey and thus your contract with Easy Parcel API.

Example of apikeyinfo request in PHP:

$ch = curl_init("https://api.easyparcel.it/apikeyinfo/c2fbbf11fdb3b18a20d543eeebdb057232c9c20b9ce850d60ce74ec36b0a8a77");                                                                      
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");                                                                     
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonRequest);                                                                  
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);                                                                      
curl_setopt($ch, CURLOPT_HTTPHEADER, array(                                                                          
	'Content-Type: application/json',                                                                                
	'Content-Length: ' . strlen($jsonRequest))                                                                       
);                                                                                                                   
$jsonResult = curl_exec($ch);

JSON Request

{
	"call":"apikeyinfo"
}

JSON Request requirements

Level 1 Type Value Required Description
call string apikeyinfo S Type "apikeyinfo"

JSON Response

{
	"response":{
		"azienda":"easyparcel.it",
		"logo":"http://www.easyparcel.it/logo.jpg",
		"system":"API",
		"lastversion":"1.1.20",
		"call":"apikeyinfo",
		"dettagli":{
			"apikey":"c2fbbf11fdb3b18a20d543eeebdb057232c9c20b9ce850d60ce74ec36b0a8a77",
			"cliente":"EasyParcel Demo",
			"attivazione":"2026-01-01",
			"scadenza":"2026-12-31",
			"ip_access":"Unlimited",
			"limite_giornaliero":"Unlimited",
			"fast_quote":"false",
			"credito_prepagato":125.00,
			"live":"true",
			"email_ordine_mittente":"true",
			"ldv_api":""
		},
		"timestamp":"2026-09-26 23:53:13"
	}
}

Notes on JSON Response:

The JSON response contains the service activation date and the date of the next expiration of the license to use the Easy Parcel API. It also contains two configuration parameters for the purchased package that provide for blocking the system on specific IP addresses of the servers where the customer's system is installed and the daily limit, if any, on quotation calls. It also contains the remaining prepaid credit that allows the API call "order" to be able to proceed to finalize the purchase of the shipment, with the prepaid being charged.
Important
The value of the live field identifies the mode of operation; if it is "false," "order" type calls do not finalize any real orders and therefore do not deduct credit.
The ldv_api field may optionally contain the address of a customer web service to which to send the tracking link and LDV (waybill) link data. It will be the customer's responsibility to store this information in their management system. The response will be of JSON type and will contain the following fields: 
{
	"result": "OK",
	"errorcode": "0",
	"errormessage": "WEBHOOK OK",
	"codice_offerta": "6513ffbc66222",
	"custom": "4102000000001348000003333002",
	"lettera_vettura": "288364I031083",
	"url_ldv": "https://api.easyparcel.it/ldv/LDV_demo.pdf",
	"url_tracking": "https://www.poste.it/cerca/index.html#/risultati-spedizioni/288364I031083"
}
The call will be made when the LDV is generated (within a couple of minutes of ordering).

Quotation

The quotation call allows you to obtain the cost estimate for a shipment, according to specific parameters that are provided. In practice, some data is required about the place of departure, the destination and the type of shipment (national/international, package specifications, etc).
The Easy Parcel API system will calculate, if possible, the shipping cost based on the system's standard carriers or on those specifically enabled for the customer (and linked to their ApiKey). The responses detail the carrier used and any optional services that can be enabled (with their related costs).

Example of quotation call in PHP:

$ch = curl_init("https://api.easyparcel.it/quotation/c2fbbf11fdb3b18a20d543eeebdb057232c9c20b9ce850d60ce74ec36b0a8a77");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonRequest);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
	'Content-Type: application/json',
	'Content-Length: ' . strlen($jsonRequest))
);
$jsonResult = curl_exec($ch);

JSON Request

{
	"call":"quotation",
	"dettagli":{
		"tipo_spedizione":"N",
		"cosa_spedire":"M",
		"contenuto":"BISCOTTI",
		"accessori":{
			"contrassegno_importo":500
		}
	},
	"colli":[
		{
			"peso":3.000,
			"larghezza":30,
			"profondita":20,
			"altezza":15,
			"nr_colli":1
		}
	],
	"mittente":{
		"cap":"00175",
		"localita":"ROMA",
		"provincia":"RM",
		"nazione":"IT"
	},
	"destinatario":{
		"cap":"20121",
		"localita":"MILANO",
		"provincia":"MI",
		"nazione":"IT"
	}
}

JSON Request Requirements

Level 1 Level 2 Level 3 Type Example Mandatory Description
call     string quotation Y Enter quotation
dettagli idcustomer   numeric 12345 optional This field can be used to indicate the id of the customer within your own network on whose price list the estimate should be calculated.
tipo_spedizione   string N Y N = national
E = abroad
I = import
cosa_spedire   string M Y D = documents
M = goods/parcels
P = pallets
contenuto   string BISCOTTI Y Enter the description of the contents
accessori contrassegno_importo decimal 250.00 optional Indicate the cash-on-delivery amount
The service may not be available for some carriers
assicurazione_importo decimal 350.00 optional Indicate the insurance amount
The service may not be available for some carriers
consegnaalpiano string S optional S = purchase
N = do not purchase
The service may not be available for some carriers
consegnasuappuntamento string S optional S = purchase
N = do not purchase
The service may not be available for some carriers
priornotice string S optional S = purchase
N = do not purchase
The "Prior Notice" service can only be purchased for foreign shipments directed to the USA
colli peso   decimal 3.000 Y Total weight of this series of packages, in kg
larghezza   integer 30 Y Width of the single package in this series of packages (in cm)
profondita   integer 20 Y Depth of the single package in this series of packages (in cm)
altezza   integer 15 Y Height of the single package in this series of packages (in cm)
nr_colli   integer 1 Y Number of packages with the same dimensions in this series of packages
mittente cap   string 00175 Y Sender's postal code
localita   string ROMA Y Sender's town
provincia   string RM Y Sender's province
nazione   string IT Y Enter IT
destinatario cap   string 20121 Y Recipient's postal code
localita   string MILANO Y Recipient's town
provincia   string MI Y Recipient's province; for international shipments enter --
country   string IT Mandatory only for international shipments to the USA and Canada Recipient's country/state, to be filled in only for the USA (link) and Canada (link)
nazione   string IT Y Recipient's country, use the ISO 3166-1 Alpha-2 code (link)

JSON Response

{
	"result":"OK",
	"errorcode":0,
	"errormessage":"QUOTATION OK",
	"quotation":[
		{
			"codice_offerta":"5dcc4a53b00fc",
			"vettore":"SDAM",
			"famiglia":"SDA",
			"nome_vettore":"SDA",
			"logo_vettore":"https://www.easyparcel.it/api/loghi/logo_sda.png",
			"consegna":"E",
			"tempiconsegna":"24/48 ore",
			"messaggio_tariffa":null,
			"importo_tariffa":"10.62",
			"totale_dovuto":"6.90",
			"peso_volumetrico":3,
			"flag_scontonazionale":null,
			"flag_localitadisagiata":false,
			"flag_localitaperiferica":false,
			"flag_timecritical":false,
			"percentualeiva":"22.00",
			"serviziopzionali":{
				"contrassegno":{
					"attivabile":"S",
					"importo":"5.00",
					"limite_massimo":"1999.99",
					"servizi":"C-A"
				},
				"assicurazione":{
					"attivabile":"S",
					"importo":"7.70",
					"limite_massimo":"3000.00",
					"valore_simulato":500
				},
				"consegnaalpiano":{
					"attivabile":"S",
					"importo":"4.00"
				},
				"consegnasuappuntamento":{
					"attivabile":"S",
					"importo":"6.00"
				},
				"trackingavanzato":{
					"attivabile":"S",
					"importo":"0.15"
				},
				"ritiro":{
					"attivabile":"S",
					"importo":"0.00"
				}
			}
		},
		{
			"codice_offerta":"5dcc4a53ae412",
			"vettore":"CROM",
			"famiglia":"SDA",
			"nome_vettore":"CRONO",
			"logo_vettore":"https://www.easyparcel.it/api/loghi/logo_cro.png",
			"consegna":"E",
			"tempiconsegna":"48 ore",
			"messaggio_tariffa":null,
			"importo_tariffa":"11.32",
			"totale_dovuto":"7.36",
			"peso_volumetrico":3,
			"flag_scontonazionale":null,
			"flag_localitadisagiata":false,
			"flag_localitaperiferica":false,
			"flag_timecritical":false,
			"percentualeiva":"22.00",
			"serviziopzionali":{
				"contrassegno":{
					"attivabile":"N"
				},
				"assicurazione":{
					"attivabile":"N"
				},
				"consegnaalpiano":{
					"attivabile":"S",
					"importo":"4.00"
				},
				"consegnasuappuntamento":{
					"attivabile":"S",
					"importo":"6.00"
				},
				"trackingavanzato":{
					"attivabile":"S",
					"importo":"0.15"
				},
				"ritiro":{
					"attivabile":"S",
					"importo":"0.00"
				}
			}
		},
		{
			"codice_offerta":"5dcc4a53af494",
			"vettore":"PCE",
			"famiglia":"SDA",
			"nome_vettore":"PACCO CELERE",
			"logo_vettore":"https://www.easyparcel.it/api/loghi/logo_pce.png",
			"consegna":"E",
			"tempiconsegna":"48 ore",
			"messaggio_tariffa":null,
			"importo_tariffa":"14.14",
			"totale_dovuto":"9.33",
			"peso_volumetrico":3,
			"flag_scontonazionale":null,
			"flag_localitadisagiata":false,
			"flag_localitaperiferica":false,
			"flag_timecritical":false,
			"percentualeiva":"22.00",
			"serviziopzionali":{
				"contrassegno":{
					"attivabile":"N"
				},
				"assicurazione":{
					"attivabile":"S",
					"importo":"6.00",
					"limite_massimo":"3000.00",
					"valore_simulato":500
				},
				"consegnaalpiano":{
					"attivabile":"N"
				},
				"consegnasuappuntamento":{
					"attivabile":"N"
				},
				"trackingavanzato":{
					"attivabile":"S",
					"importo":"0.15"
				},
				"ritiro":{
					"attivabile":"S",
					"importo":"0.00"
				}
			}
		}
	],
	"timestamp":"2026-09-26 23:53:13",
	"version":"1.1.20"
}

Notes on the JSON response:

The JSON response contains an array of quotations offered by the various Carriers connected to the Easy Parcel API system. Each offer is identified by a codice_offerta which must then be used in the "order" call to identify the estimate for purchasing the shipment. For each offer the reference carrier is returned, along with its logo, the amount due and also a series of additional information relating to any optional services that can be requested.

Order

The order call finalizes the order of a shipment, according to the specifications of a previous quotation, which must be indicated as the reference codice_offerta.
To complete the order, you must specify additional mandatory data regarding the sender and recipient names and the specification of any requested optional services, whose offers are contained in the referenced "quotation".
The Easy Parcel API system will reprocess everything, first verifying that the prepaid credit balance is sufficient. If the outcome is positive, the costs will be charged to the prepaid credit and the order is generated, which will be transmitted to the processing center for the subsequent management phases (sending confirmation email, generating the waybill, etc.).

Example of order call in PHP:

$ch = curl_init("https://api.easyparcel.it/order/c2fbbf11fdb3b18a20d543eeebdb057232c9c20b9ce850d60ce74ec36b0a8a77");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonRequest);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
	'Content-Type: application/json',
	'Content-Length: ' . strlen($jsonRequest))
);
$jsonResult = curl_exec($ch);

JSON Request

{
	"call":"order",
	"dettagli":{
		"codice_offerta":"5dcc4a53b00fc",
		"note_cliente":"ACQUISTO DI TEST",
		"custom":"XYZ123456",
		"accessori":{
			"trackingavanzato":"S"
		}
	},
	"mittente":{
		"nominativo":"Rossi Mario",
		"indirizzo":"Via del Colosseo, 1",
		"email":"mario@rossi.it",
		"telefono":"",
		"cellulare":"3471111111",
		"contatto":"Rossi Mario",
		"codicefiscale":"RSSMRA80A01H501U"
	},
	"destinatario":{
		"nominativo":"Verdi Giuseppe",
		"indirizzo":"Piazza Duomo, 1",
		"email":"giuseppe@verdi.it",
		"telefono":"",
		"cellulare":"3472222222",
		"contatto":"Verdi Giuseppe"
	},
	"ritiro":{
		"prenotazione":"S",
		"dettagli":{
			"ritirodove":"M",
			"disponibile_dal":"2026-09-26",
			"disponibile_ora":"08:00",
			"ritiro_mattina_dalle":"08:00",
			"ritiro_mattina_alle":"12:00",
			"ritiro_pomeriggio_dalle":"14:00",
			"ritiro_pomeriggio_alle":"18:00"
		}
	}
}

JSON Request Requirements

Level 1 Level 2 Level 3 Type Example Mandatory Description
call     string order Y Enter order
dettagli codice_offerta   string 5dcc4a53b00fc Y Enter a codice_offerta from those received in response to the previous "quotation" call
note_cliente   string ACQUISTO DI TEST optional Enter a text describing the purchase
custom   string XYZ123456 optional Free-text custom field for possible order search
coupon   string ILOVEUSA21 optional Enter the code of a possible discount coupon.
N.B. The coupon should first be verified with the CheckCoupon call.
accessori contrassegno string S optional S = purchase
N = do not purchase
The service may not be available for some carriers
assicurazione string S optional S = purchase
N = do not purchase
The service may not be available for some carriers
consegnaalpiano string S optional S = purchase
N = do not purchase
The service may not be available for some carriers
consegnasuappuntamento string S optional S = purchase
N = do not purchase
The service may not be available for some carriers
trackingavanzato string S optional S = purchase
N = do not purchase
priornotice string S optional S = purchase
N = do not purchase
The "Prior Notice" service can only be purchased for foreign shipments directed to the USA
mittente nominativo   string Rossi Mario Y Sender name
indirizzo   string Via del Colosseo, 1 Y Sender address
email   string mario@rossi.it Y Sender email address
telefono   string 0611111111 optional Sender landline phone
cellulare   string 3471111111 Y Sender mobile phone
contatto   string Rossi Mario Y Sender contact
codicefiscale   string RSSMRA80A01H501U Y Sender tax code
destinatario nominativo   string Verdi Giuseppe Y Recipient name
indirizzo   string Piazza Duomo, 1 Y Recipient address
email   string giuseppe@verdi.it Y Recipient email address
telefono   string 0222222222 optional Recipient landline phone
cellulare   string 34722222222 Y Recipient mobile phone
contatto   string Verdi Giuseppe Y Recipient contact
codicefiscale   string VRDGPP80A01H501U optional Recipient tax code
ritiro prenotazione   string S optional S = requested
N = not requested
The service consists of collecting the shipment at the sender's location.
dettagli ritirodove string M Y M = at the Sender's address
P = at the Point's address, indicated in the idcustomer field of the quotation call.
disponibile_dal date 2026-09-26 Y Date (in AAAA-MM-DD format) identifying from when the shipment is available for collection.
disponibile_ora time 08:00 Y Time (in HH:MM format) identifying from when the shipment is available for collection.
ritiro_mattina_dalle time 08:00 Y Time (in HH:MM format) identifying from when the shipment is available for collection.
ritiro_mattina_alle time 12:00 Y Time (in HH:MM format) identifying from when the shipment is available for collection.
ritiro_pomeriggio_dalle time 14:00 Y Time (in HH:MM format) identifying from when the shipment is available for collection.
ritiro_pomeriggio_alle time 18:00 Y Time (in HH:MM format) identifying from when the shipment is available for collection.
dettagli > documenti (PDF customs documents)
dettagli documenti[] tipo_documento string export_declaration Conditional Document type: export_declaration (free export declaration), proforma (proforma invoice), invoice (commercial invoice), extra (accessory documents, multiple). The attachments are collected into the order's "Extra Documents" and, for UPS/DHL carriers, are automatically attached to the shipment (paperless).
nome_filestringpacking_list.pdfOptionalFile name (used for documents of type extra).
contenuto_base64stringJVBERi0xLjQ...ConditionalContent of the PDF file encoded in base64 (max 15 MB).
destinatario > country (state code for US/CA shipments)
destinatariocountry stringNYConditionalState/province code for shipments to US and Canada. Mandatory for such destinations: if missing, the order is rejected (errorcode 178).

JSON Response

{
	"result":"OK",
	"errorcode":"0",
	"errormessage":"ACQUISTO OK",
	"codice_offerta":"5dcc4a53b00fc",
	"custom":"XYZ123456",
	"ordine":"EAS-5dcc4a53b00fc",
	"id_ordine":"1234567",
	"importo":"6.90",
	"timestamp":"2026-09-26 23:53:13",
	"version":"1.1.20"}

OrderFast

Performs quotation + order + waybill generation in a single call.
Endpoint: POST https://api.easyparcel.it/order-fast/{APIKEY}.

PHP example:

$url = "https://api.easyparcel.it/order-fast/{APIKEY}";

$json = array(
	"call" => "order-fast",
	"details" => array(
		"client_notes" => "TEST-SHIPMENT",
		"content_notes" => "TEST-CONTENT",
		"return_waybill_file" => TRUE,
		"customer_id" => 15,
		"carrier_code" => "SDAM",
		"what_to_ship" => "M",
		"custom" => "CUSTOMTEST",
		"shipment_type" => "N",
		"accessories" => array(
			"cash_on_delivery_amount" => 1000,
			"cash_on_delivery" => "Y",
			"insurance_amount" => 500,
			"insurance" => "Y",
			"floor_delivery" => "N",
			"appointment_delivery" => "N",
			"prior_notice" => "N",
			"assigned_port" => "N",
			"recipient_pudo" => "",
			"sender_pudo" => "",
			"reverse" => "N"
		)
	),
	"packages" => array(
		array(
			"weight" => 1.000,
			"width" => 20,
			"depth" => 22,
			"height" => 24,
			"number_of_packages" => 1
		)
	),
	"sender" => array(
		"name" => "ROSSI MARIO",
		"address" => "VIA COLOSSEO, 1",
		"postal_code" => "00175",
		"city" => "ROMA",
		"province" => "RM",
		"country_code" => "IT",
		"email" => "mario@rossi.it",
		"phone" => "",
		"mobile" => "3471111111",
		"contact" => "ROSSI MARIO",
		"tax_code" => "RSSMRA80A01H501U"
	),
	"recipient" => array(
		"name" => "VERDI GIUSEPPE",
		"address" => "PIAZZA DUOMO, 1",
		"postal_code" => "20121",
		"city" => "MILANO",
		"province" => "MI",
		"country_code" => "IT",
		"email" => "giuseppe@verdi.it",
		"phone" => "",
		"mobile" => "3472222222",
		"contact" => "VERDI GIUSEPPE",
		"tax_code" => ""
	),
	"pickup" => array(
		"reservation" => "Y",
		"details" => array(
			"pickup_where" => "M",
			"available_from" => "2025-01-15",
			"available_time" => "08:00",
			"pickup_morning_from" => "08:00",
			"pickup_morning_to" => "12:00",
			"pickup_afternoon_from" => "14:00",
			"pickup_afternoon_to" => "18:00"
		)
	)
);

$jsonRequest = json_encode($json);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonRequest);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
	'Content-Type: application/json',
	'Content-Length: ' . strlen($jsonRequest)
));
$result = curl_exec($ch);
$response = json_decode($result, TRUE);
print_r($response);

JSON Request Example

{
	"call": "order-fast",
	"details": {
		"client_notes": "TEST-SHIPMENT",
		"content_notes": "Various goods",
		"return_waybill_file": true,
		"customer_id": 15,
		"carrier_code": "SDAM",
		"what_to_ship": "M",
		"custom": "CUSTOMTEST",
		"shipment_type": "N",
		"accessories": {
			"cash_on_delivery_amount": 1000,
			"cash_on_delivery": "Y",
			"insurance_amount": 500,
			"insurance": "Y",
			"floor_delivery": "N",
			"appointment_delivery": "N",
			"prior_notice": "N",
			"assigned_port": "N",
			"recipient_pudo": "",
			"sender_pudo": "",
			"reverse": "N"
		},
		"hscodes": [
			{
				"hscode": "3004.90.10",
				"description": "GENERIC MEDICINE",
				"quantity": 2,
				"amount": 15.00,
				"weight": 0.100,
				"export_reason": "SALE"
			}
		]
	},
	"packages": [
		{
			"weight": 1.000,
			"width": 20,
			"depth": 22,
			"height": 24,
			"number_of_packages": 1
		}
	],
	"sender": {
		"name": "ROSSI MARIO",
		"address": "VIA COLOSSEO, 1",
		"postal_code": "00175",
		"city": "ROMA",
		"province": "RM",
		"country_code": "IT",
		"email": "mario@rossi.it",
		"phone": "",
		"mobile": "3471111111",
		"contact": "ROSSI MARIO",
		"tax_code": "RSSMRA80A01H501U"
	},
	"recipient": {
		"name": "VERDI GIUSEPPE",
		"address": "PIAZZA DUOMO, 1",
		"postal_code": "20121",
		"city": "MILANO",
		"province": "MI",
		"country_code": "IT",
		"email": "giuseppe@verdi.it",
		"phone": "",
		"mobile": "3472222222",
		"contact": "VERDI GIUSEPPE",
		"tax_code": ""
	},
	"pickup": {
		"reservation": "Y",
		"details": {
			"pickup_where": "M",
			"available_from": "2025-01-15",
			"available_time": "08:00",
			"pickup_morning_from": "08:00",
			"pickup_morning_to": "12:00",
			"pickup_afternoon_from": "14:00",
			"pickup_afternoon_to": "18:00"
		}
	}
}

Request Parameters Table

Level1 Level2 Level3 Type Example Required Description
call string order-fast Yes Call type. Must be order-fast
details
details client_notes string TEST-SHIPMENT Optional Customer-visible notes on the shipment
content_notes string Various goods Optional Description of the shipment content
return_waybill_file boolean true Optional If true, returns the waybill PDF in base64 in the ldv_base64 field
customer_id integer 15 Optional Customer ID for specific tariff calculation (not public)
carrier_code string SDAM Yes Carrier code for the shipment (e.g. SDAM, PDB, INPOST, BRT, GLS, etc.)
what_to_ship string M Yes Type of goods: M = Merchandise, D = Documents, P = Pallets
custom string CUSTOMTEST Optional Customer custom reference. Returned in the response.
shipment_type string N Yes Shipment type: N = National, E = Abroad (export, to any foreign country), I = Import (from abroad to Italy)
details > accessories
details accessories cash_on_delivery string Y Optional Enable cash on delivery. Y = Yes, N = No. If the service is not available for the carrier, the order is blocked (error 175).
cash_on_delivery_amount decimal 1000 Conditional Cash on delivery amount. Required if cash_on_delivery=Y. If it exceeds the carrier's maximum limit, the order is blocked.
insurance string Y Optional Enable insurance. Y = Yes, N = No. If the service is not available for the carrier, the order is blocked (error 175).
insurance_amount decimal 500 Conditional Insurance amount. Required if insurance=Y. If it exceeds the carrier's maximum limit, the order is blocked.
floor_delivery string Y Optional Floor delivery. Y = Yes, N = No. Subject to carrier availability.
appointment_delivery string Y Optional Delivery by appointment. Y = Yes, N = No. Subject to carrier availability.
prior_notice string Y Optional Prior phone notice. Y = Yes, N = No. Subject to carrier availability.
assigned_port string Y Optional Assigned port (charges paid by recipient). Y = Yes, N = No. Subject to carrier availability.
recipient_pudo string Z6426 Conditional Recipient PUDO code. For PDB: code obtained from the pudo call (validated against pdb_pudo table). For INPOST: locker code (validated against inpost_punti table), required together with sender_pudo.
sender_pudo string Z1234 Conditional Sender PUDO code. For PDB: only available for reverse shipments. For INPOST: required together with recipient_pudo, the two codes must be different from each other.
reverse string Y Optional Reverse shipment (return). Y = active, N = not active (default). Available for PDB.
details > hscodes (required for non-EU countries with customs)
details hscodes[] hscode string 3004.90.10 Yes HS (Harmonized System) code. Format: 6-10 digits, with or without dots. The first 6 digits are validated against the international WCO database.
description string Medicine Yes Description of the goods in natural language.
quantity integer 2 Yes Number of items. Must be greater than 0.
amount decimal 15.00 Yes Value of the goods in EUR.
weight decimal 0.100 Yes Weight of the goods in kg.
export_reason string SALE Yes Reason for export. Common values: SALE, GIFT, SAMPLE, RETURN, REPAIR, PERSONAL_EFFECTS.
details > documents (customs PDF documents)
details documents[] document_type string export_declaration Conditional Document type: export_declaration (free export declaration), proforma (proforma invoice), invoice (commercial invoice), extra (additional documents, multiple). Attachments go into the order "Extra Documents" and, for UPS/DHL carriers, are automatically attached to the shipment (paperless).
document_filename string packing_list.pdf Optional File name (used for extra documents).
document_base64 string JVBERi0xLjQ... Conditional Base64-encoded PDF content (PDF only, max 15 MB).
packages
packages[] weight decimal 1.000 Yes Package weight in kg
width integer 20 Yes Package width in cm
depth integer 22 Yes Package depth in cm
height integer 24 Yes Package height in cm
number_of_packages integer 1 Yes Number of packages with these dimensions
sender
sender name string ROSSI MARIO Yes Sender name / company name
address string VIA COLOSSEO, 1 Yes Sender address
postal_code string 00175 Yes Sender postal code
city string ROMA Yes Sender city
province string RM Yes Sender province code
country_code string IT Yes Sender country code (ISO 3166-1 alpha-2)
email string mario@rossi.it Optional Sender email
phone string 0612345678 Optional Sender phone number
mobile string 3471111111 Optional Sender mobile number
contact string ROSSI MARIO Optional Sender contact person
tax_code string RSSMRA80A01H501U Optional Sender tax code or VAT number
recipient
recipient name string VERDI GIUSEPPE Yes Recipient name / company name
address string PIAZZA DUOMO, 1 Yes Recipient address
postal_code string 20121 Yes Recipient postal code
city string MILANO Yes Recipient city
province string MI Yes Recipient province code
country_code string IT Yes Recipient country code (ISO 3166-1 alpha-2)
email string giuseppe@verdi.it Optional Recipient email
phone string 0287654321 Optional Recipient phone number
mobile string 3472222222 Optional Recipient mobile number
contact string VERDI GIUSEPPE Optional Recipient contact person
tax_code string Optional Recipient tax code or VAT number
state_code string CA Conditional State/province code for shipments to US/CA (e.g. US state or Canadian province)
pickup
pickup reservation string Y Optional Pickup reservation. Y = Yes, N = No
details pickup_where string M Conditional Pickup location (required if reservation=Y)
available_from string 2025-01-15 Conditional Pickup availability date (YYYY-MM-DD format)
available_time string 08:00 Conditional Pickup availability time (HH:MM format)
pickup_morning_from string 08:00 Conditional Morning pickup start time
pickup_morning_to string 12:00 Conditional Morning pickup end time
pickup_afternoon_from string 14:00 Conditional Afternoon pickup start time
pickup_afternoon_to string 18:00 Conditional Afternoon pickup end time

JSON Response

{
	"result": "OK",
	"errorcode": "",
	"errormessage": "",
	"codice_offerta": "QUO-123456",
	"custom": "CUSTOMTEST",
	"ordine": "ORD-123456",
	"id_ordine": 789012,
	"importo": "8.50",
	"lettera_vettura": "1Z999AA10123456784",
	"url_ldv": "https://api.easyparcel.it/getwaybill/...",
	"codice_ritiro": "RIT-123456",
	"url_bordero": "https://api.easyparcel.it/getbordero/...",
	"ldv_base64": "JVBERi0xLjQKMS...",
	"single_waybills": [
		{
			"lettera_vettura": "1Z999AA10123456784",
			"ldv_base64": "JVBERi0xLjQKMS..."
		}
	],
	"timestamp": "2025-01-15 10:30:00",
	"version": "1.1.20"
}

Note

  • If an accessory service not available for the selected carrier is requested (e.g. cash on delivery, insurance, floor delivery, pickup), the order is blocked with a specific error (errorcode 175).
  • If the cash on delivery or insurance amount exceeds the maximum limit for the carrier, the order is blocked.
  • For INPOST shipments, both sender_pudo and recipient_pudo fields are required and must contain valid locker codes that are different from each other.
  • For shipments to countries with customs (non-EU with dogana=1), the hscodes field is required. Each item must have a valid HS code (verified against the international 6-digit database), description, quantity, value, weight and export reason. Invalid HS codes will block the order.
  • The single_waybills field contains individual waybill pages for multi-parcel shipments, each with its own waybill number and base64 PDF.

GetWaybill

The GetWaybill call allows you to obtain information related to the WAYBILL (AWB or waybill) of a specific order.

Example of getwaybill call in PHP:

$ch = curl_init("https://api.easyparcel.it/getwaybill/c2fbbf11fdb3b18a20d543eeebdb057232c9c20b9ce850d60ce74ec36b0a8a77");                                                                      
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");                        
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonRequest);                        
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);                        
curl_setopt($ch, CURLOPT_HTTPHEADER, array
	(
		'Content-Type: application/json',
		'Content-Length: ' . strlen($jsonRequest)
	)
);                        
$jsonResult = curl_exec($ch);

JSON Request

{
	"call":"getwaybill",
	"details": {
		"order_id":1234567,
		"waybill_base64":"Y"
		"single_waybills":"Y"
	}
}

JSON Request Requirements

Level 1 Level 2 Type Value Mandatory Description
call   string getwaybill Y Enter "getwaybill"
details order_id numeric 1234567 Y This field must indicate the order ID for which the waybill is requested.
waybill_base64 string N optional Y = returns the content of the waybill file encoded in base64
N = does not return the content of the waybill file
Note: By default, if not passed, this value is assumed to be N.
single_waybills string N optional Y = returns the content of individual waybills encoded in base64 inside "single_waybills"
N = does not return individual waybills
Note: By default, if not passed, this value is assumed to be N.

JSON Response

{
	"result":"OK",
	"error_code":0,
	"error_message":"GETWAYBILL OK",
	"order_id":"1234567",
	"custom":"ORD.123",
	"waybill_number":"288988I018728",
	"waybill_url":"https://api.easyparcel.it/ldv/5188175_66620f9322512.pdf",
	"pickup_code":"CP95599292",
	"bordero_url":"https://api.easyparcel.it/tmp/202_bordero_20240607000033.pdf",
	"waybill_base64":"JVBERi0xLjQKJeLjz9MKNCAwIG9iago8PC9Db2xvclNwYWNv3r4rLCxCTVPiwIHj/wdBQUGjhw3...NDEzNTY2CiUlRU9GCg==",
	"single_waybills":[
		{
			"waybill_number":"288988I018728",
			"waybill_base64":"JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlIC9QYWdlCi9QYXJlbnQgMSAwIFIKL01lZGl...ZgoyMDUwNDMKJSVFT0Y="
		},
		{
			"waybill_number":"988IMFVYK288988I018728",
			"waybill_base64":"JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlIC9QYWdlCi9QYXJlbnQgMSAwIFIKL01lZGl...ZgoyMTAxNDAKJSVFT0Y="
		}
	],
	"timestamp":"2026-09-26 23:53:13",
	"version":"1.1.20"
}

Notes on the JSON response:

The JSON response contains all the data, if present, related to the Waybill, including its number and the URL where it can be downloaded. If the parameter waybill_base64 with the value Y was included in the request, then the response will also contain the field waybill_base64 which will include the content of the waybill file encoded in "base64" standard that can be saved and made available to customers. Additionally, if the parameter single_waybills with the value Y was included in the request, the response will contain the field single_waybills with the content of individual waybills encoded in base64. When the order has attached documents (export declaration, invoice, extra attachments), the response also includes a documenti field: an array of objects with tipo, filename and url (a temporary "presigned" link valid for 1 hour to download the PDF).

TARIC Search

Assisted lookup of TARIC/HS codes from a natural-language product description.
Endpoint: POST https://api.easyparcel.it/taric-search/{APIKEY}.
The returned code must be passed to order-fast inside details.hscodes[].hscode for international shipments (required for countries with customs and for every foreign destination with PDBPLUS).

PHP example:

$url = "https://api.easyparcel.it/taric-search/{APIKEY}";

$json = array(
    "call" => "taric-search",
    "q" => "chocolate biscuits",
    "lang" => "en",
    "limit" => 5
);

$jsonRequest = json_encode($json);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonRequest);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-Type: application/json'
));
$result = curl_exec($ch);
$response = json_decode($result, TRUE);
print_r($response);

Alternatively, parameters can be passed in the query string:
GET https://api.easyparcel.it/taric-search/{APIKEY}?q=chocolate+biscuits&lang=en&limit=5

JSON Request Example

{
    "call": "taric-search",
    "q": "chocolate biscuits",
    "lang": "en",
    "limit": 5
}

Request Parameters Table

Field Type Example Required Description
call string taric-search Yes Call type. Must be taric-search (only needed when using the JSON body).
q string chocolate biscuits Yes Product description in natural language (Italian or English).
lang string en Optional Search language: it (default) or en.
limit integer 5 Optional Maximum number of results (1 to 10, default 5).

JSON Response

{
    "result": "OK",
    "call": "taric-search",
    "query": "chocolate biscuits",
    "results": [
        {
            "taric_code": "1905310000",
            "description_it": "Biscotti dolci",
            "description_en": "Sweet biscuits",
            "confidence": 0.92
        }
    ],
    "timestamp": "2026-06-15 10:30:00"
}

Response Fields (results[])

Field Type Example Description
taric_code string 1905310000 10-digit TARIC code. Use it in order-fast as details.hscodes[].hscode (the first 6 digits are validated).
description_it string Biscotti dolci Official Italian description.
description_en string Sweet biscuits Official English description.
confidence decimal 0.92 Estimated match score (0.0 - 1.0). Results are sorted by descending confidence.

Notes

  • Authentication via API key, in the path (/taric-search/{APIKEY}) or in the X-API-KEY header.
  • The service only returns codes present in the customs catalogue: invalid suggestions are filtered out automatically.
  • The quantity, amount, weight and export_reason fields required by order-fast are NOT provided by this search: they must be filled in by the client based on the goods.
  • If the search returns no results, try a more specific description or use English.

GetOrder

The getorder call allows you to view all the information related to a shipment order, and it can be searched by codice_offerta or by custom.

Example of getorder call in PHP:

$ch = curl_init("https://api.easyparcel.it/getorder/c2fbbf11fdb3b18a20d543eeebdb057232c9c20b9ce850d60ce74ec36b0a8a77");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonRequest);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
	'Content-Type: application/json',
	'Content-Length: ' . strlen($jsonRequest))
);
$jsonResult = curl_exec($ch);

JSON Request

{
	"call":"getorder",
	"dettagli":{
		"codice_offerta":"5dcc4a53b00fc",
		"custom":"XYZ123456"
	}
}

JSON Request Requirements

Level 1 Level 2 Type Example Mandatory Description
call   string getorder Y Enter getorder
dettagli codice_offerta string 5dcc4a53b00fc optional Enter a codice_offerta from those received in response to a previous "order" call.
Note: If not entered, the custom field becomes mandatory.
custom string XYZ123456 optional Enter a custom from those specified in a previous "order" call.
Note: If not entered, the codice_offerta field becomes mandatory.

JSON Response

{
	"result":"OK",
	"errorcode":0,
	"errormessage":"GETORDER OK",
	"order":{
		"codice_offerta":"5dcc4a53b00fc",
		"data":"2026-01-03 10:41:08",
		"utente":"0",
		"ragionesociale":"ROSSI MARIO",
		"indirizzo":"VIA DEL COLOSSEO, 1",
		"cap":"00175",
		"localita":"ROMA",
		"provincia":"RM",
		"codicefiscale":"RSSMRA80A01H501U",
		"partitaiva":"",
		"telefono":"",
		"cellulare":"3471111111",
		"email":"mario@rossi.it",
		"cosa":"MERCE",
		"peso_totale":"1.000",
		"tipo_spedizione":"N",
		"vettore":"SDAM",
		"nome_vettore":"SDA",
		"logo_vettore":"https://www.easyparcel.it/api/loghi/logo_sda.png",
		"mittente_nominativo":"ROSSI MARIO",
		"mittente_indirizzo":"VIA DEL COLOSSEO, 1",
		"mittente_localita":"ROMA",
		"mittente_provincia":"RM",
		"mittente_cap":"00175",
		"mittente_email":"mario@rossi.it",
		"mittente_telefono":"",
		"mittente_cellulare":"3471111111",
		"mittente_contatto":"ROSSI MARIO",
		"mittente_cf":"RSSMRA80A01H501U",
		"destinatario_nominativo":"VERDI GIUSEPPE",
		"destinatario_indirizzo":"PIAZZA DUOMO, 1",
		"destinatario_localita":"MILANO",
		"destinatario_cap":"20121",
		"destinatario_provincia":"MI",
		"destinatario_nazione":"IT",
		"destinatario_esterocap":null,
		"destinatario_country":null,
		"destinatario_email":"giuseppe@verdi.it",
		"destinatario_telefono":"",
		"destinatario_cellulare":"3472222222",
		"destinatario_contatto":"VERDI GIUSEPPE",
		"consegna":"E",
		"totale_dovuto":"6.90",
		"percentualeiva":"22",
		"importo_tariffa":"10.62",
		"peso_volumetrico":"1.000",
		"contrassegno":"N",
		"contrassegno_importo":"0.00",
		"contrassegno_modalita":"C",
		"assicurazione":"N",
		"assicurazione_importo":"0.00",
		"consegnaalpiano":"N",
		"appuntamento":"N",
		"priornotice":"N",
		"ritiro":"N",
		"ritiro_dove":null,
		"ritiro_disp_data":null,
		"ritiro_disp_ora":null,
		"ritiro_matt_da":null,
		"ritiro_matt_a":null,
		"ritiro_pom_da":null,
		"ritiro_pom_a":null,
		"note_cliente":"ACQUISTO DI TEST",
		"note_contenuto":"BISCOTTI",
		"custom":"XYZ123456",
		"lettera_vettura":null,
		"url_ldv":null,
		"codice_ritiro":null,
		"live":"0",
		"idordine":1234567,
		"url_bordero":"https://api.easyparcel.it/tmp/1234_bordero_20230208160810.pdf"
	},
	"dettagli":[
		{
			"peso":"3.000",
			"larghezza":"30",
			"profondita":"20",
			"altezza":"15",
			"nr_colli":"1"
		}
	],
	"timestamp":"2026-09-26 23:53:13",
	"version":"1.1.20"
}

Notes on the JSON response:

The JSON response contains all the data related to the storage of the order

ListOrder

The listorder call allows you to obtain a list of shipments filtered by the selected period and/or user id.

Example of listorder call in PHP:

$ch = curl_init("https://api.easyparcel.it/listorder/c2fbbf11fdb3b18a20d543eeebdb057232c9c20b9ce850d60ce74ec36b0a8a77");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonRequest);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
	'Content-Type: application/json',
	'Content-Length: ' . strlen($jsonRequest))
);
$jsonResult = curl_exec($ch);

JSON Request

{
	"call":"listorder",
	"dettagli":{
		"data_inizio":"2024-01-01",
		"data_fine":"2024-01-15",
		"idcustomer":"12345",
		"paginazione":25,
		"pagina":3
	}
}

JSON Request Requirements

Level 1 Level 2 Type Example Mandatory Description
call   string listorder Y Enter listorder
dettagli data_inizio string 2024-01-01 optional Enter a period start date in the format YYYY-MM-DD.
Note: If not entered, today's date is used.
data_fine string 2024-01-15 optional Enter a period end date in the format YYYY-MM-DD.
Note: If not entered, today's date is used.
idcustomer numeric 12345 optional Enter the ID of a user within your own network.
Note: If not entered, the list of all orders is shown.
paginazione numeric 25 optional Enter the pagination size, i.e. the number of orders that will be returned by the call.
Note: If not entered, the list of the first 10 orders is shown; the maximum pagination is 100 orders.
pagina numeric 2 optional Enter the number of the page to display.
Note: If not entered, the first page of the order list is shown.

JSON Response

{
	"result":"OK",
	"errorcode":0,
	"errormessage":"LISTORDER OK",
	"nrordini":38,
	"paginazione":25,
	"pagina":2,
	"orders":[
		{
			"codice_offerta":"5dcc4a53b00fc",
			"data":"2020-04-14 18:41:08",
			"cosa":"MERCE",
			"peso_totale":"1.000",
			"tipo_spedizione":"N",
			"vettore":"SDAM",
			"nome_vettore":"SDA",
			"logo_vettore":"https://www.easyparcel.it/api/loghi/logo_sdam.png",				
			"mittente_nominativo":"Rossi Mario",
			"mittente_localita":"ROMA",
			"mittente_provincia":"RM",
			"mittente_cap":"00175",
			"destinatario_nominativo":"Verdi Giuseppe",
			"destinatario_localita":"MILANO",
			"destinatario_cap":"20121",
			"destinatario_provincia":"MI",
			"destinatario_nazione":"IT",
			"destinatario_esterocap":null,
			"destinatario_country":null,
			"consegna":"E",
			"totale_dovuto":"6.90",
			"peso_volumetrico":"1.000",
			"note_cliente":"ACQUISTO DI TEST",
			"note_contenuto":"BISCOTTI",
			"custom":"XYZ123456",
			"lettera_vettura":null,
			"idcustomer":"12345",
			"live":"0",
			"colli":[
				{
					"nr_colli":"1",
					"lunghezza":"10",
					"larghezza":"20",
					"altezza":"30",
					"peso":"3.500"
				}
			]
		},
		{
			"codice_offerta":"5dcc4a53b00fg",
			"data":"2020-04-14 18:55:32",
			"cosa":"MERCE",
			"peso_totale":"3.000",
			"tipo_spedizione":"N",
			"vettore":"SDAM",
			"nome_vettore":"SDA",
			"logo_vettore":"https://www.easyparcel.it/api/loghi/logo_sdam.png",				
			"mittente_nominativo":"Rossi Maria",
			"mittente_localita":"ROMA",
			"mittente_provincia":"RM",
			"mittente_cap":"00178",
			"destinatario_nominativo":"Verdi Giuseppina",
			"destinatario_localita":"MILANO",
			"destinatario_cap":"20128",
			"destinatario_provincia":"MI",
			"destinatario_nazione":"IT",
			"destinatario_esterocap":null,
			"destinatario_country":null,
			"consegna":"E",
			"totale_dovuto":"8.20",
			"peso_volumetrico":"3.000",
			"note_cliente":"ACQUISTO DI TEST",
			"note_contenuto":"VESTITI",
			"custom":"XYZ123457",
			"lettera_vettura":null,
			"idcustomer":"12345",
			"live":"0",
			"colli":[
				{
					"nr_colli":"1",
					"lunghezza":"18",
					"larghezza":"28",
					"altezza":"3",
					"peso":"0.454"
				}
			]
		}
	],
	"timestamp":"2024-01-19 09:31:59"
}

Notes on the JSON response:

The JSON response contains the paginated list of orders for the selected period and, optionally, for the selected user, with some identifying data for each order.

Tracking

The tracking call allows you to obtain the link to view the tracking of a shipment, which can be searched by codice_offerta, by custom or through ldv.

Example of tracking call in PHP:

$ch = curl_init("https://api.easyparcel.it/tracking/c2fbbf11fdb3b18a20d543eeebdb057232c9c20b9ce850d60ce74ec36b0a8a77");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonRequest);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
	'Content-Type: application/json',
	'Content-Length: ' . strlen($jsonRequest))
);
$jsonResult = curl_exec($ch);

JSON Request

{
	"call":"tracking",
	"dettagli":{
		"codice_offerta":"5dcc4a53b00fc",
		"custom":"XYZ123456"
	}
}

JSON Request Requirements

Level 1 Level 2 Type Example Mandatory Description
call   string tracking Y Enter tracking
dettagli codice_offerta string 5dcc4a53b00fc optional Enter a codice_offerta from those received in response to a previous "order" call.
Note: You must indicate a codice_offerta, a custom or a ldv.
custom string XYZ123456 optional Enter a custom from those indicated in a previous "order" call.
Note: You must indicate a codice_offerta, a custom or a ldv.
ldv string 288016E049120 optional Enter a ldv to search for.
Note: You must indicate a codice_offerta, a custom or a ldv.

JSON Response

{
	"result":"OK",
	"errorcode":0,
	"errormessage":"TRACKING OK",
	"tracking":{
		"codice_offerta":"5e95d42de07a6",
		"custom":"XYZ123456",
		"lettera_vettura":"288016E049120",
		"url_tracking":"https://www.poste.it/cerca/index.html#/risultati-spedizioni/288364I031083",
		"codice_prenotazione":"CP1234567890"
	},
	"dettagli":[
		{
			"id": 1,
			"data":"2020-04-15",
			"ora":"12:41:00",
			"status":"RIT",
			"descrizione":"RITIRATA",
			"note":"LA SPEDIZIONE E' STATA RITIRATA PRESSO IL MITTENTE",
			"filiale":"Catanzaro"
		},
		{
			"id": 2,
			"data":"2020-04-15",
			"ora":"16:10:02",
			"status":"PPP",
			"descrizione":"PARTITA",
			"note":"LA SPEDIZIONE E' PARTITA",
			"filiale":"Catanzaro"
		},
		{
			"id": 3,
			"data":"2020-04-16",
			"ora":"10:54:00",
			"status":"PPP",
			"descrizione":"PARTITA",
			"note":"LA SPEDIZIONE E' PARTITA",
			"filiale":"Roma Hub Espresso"
		},
		{
			"id": 4,
			"data":"2020-04-16",
			"ora":"10:55:00",
			"status":"THE",
			"descrizione":"SMISTATO HUB ED INOLTRATO",
			"note":"IN TRANSITO",
			"filiale":"Roma Hub Espresso"
		},
		{
			"id": 5,
			"data":"2020-04-17",
			"ora":"04:18:00",
			"status":"PPP",
			"descrizione":"PARTITA",
			"note":"LA SPEDIZIONE E' PARTITA",
			"filiale":"Hub Espresso Piacenza"
		},
		{
			"id": 6,
			"data":"2020-04-17",
			"ora":"04:18:00",
			"status":"THE",
			"descrizione":"SMISTATO HUB ED INOLTRATO",
			"note":"IN TRANSITO",
			"filiale":"Hub Espresso Piacenza"
		},
		{
			"id": 7,
			"data":"2020-04-17",
			"ora":"12:25:00",
			"status":"000",
			"descrizione":"LA SPEDIZIONE E' STATA CONSEGNATA",
			"note":"LA SPEDIZIONE E' STATA CONSEGNATA",
			"filiale":"Hub Espresso Piacenza",
			"firma":"Rossi Mario"
		}
	],
	"timestamp":"2024-01-19 09:31:59"
}

Notes on the JSON response:

The JSON response contains all the data related to the tracking of the shipment, and for the SDA carrier the full detail is also available in the dedicated field.

NewCustomer

The newcustomer call allows you to create a new user in your network.

Example of newcustomer call in PHP:

$ch = curl_init("https://api.easyparcel.it/newcustomer/c2fbbf11fdb3b18a20d543eeebdb057232c9c20b9ce850d60ce74ec36b0a8a77");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonRequest);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
	'Content-Type: application/json',
	'Content-Length: ' . strlen($jsonRequest))
);
$jsonResult = curl_exec($ch);

JSON Request

{
	"call":"newcustomer",
	"dettagli":{
		"cognome":"ROSSI",
		"nome":"MARIO",
		"indirizzo":"PIAZZA DUOMO, 1",
		"cap":"20121",
		"localita":"MILANO",
		"provincia":"MI",
		"nazione":"IT",
		"email":"mariorossi@gmail.com",
		"telefono":"0212345678",
		"cellulare":"3470123456",
		"ragionesociale":"ROSSI MARIO SLRS",
		"codicefiscale":"RSSMRA11A11A111A",
		"partitaiva":"01234567890",
		"fe_pec":"rossimario@pec.it",
		"fe_sdi":"0000000",
		"banca":null,
		"iban":null,
		"intestazioneconto":null,
		"username":"mariorossi",
		"password":"12345678"
	}
}

JSON Request Requirements

Level 1 Level 2 Type Example Mandatory Description
call   string newcustomer Y Enter newcustomer
dettagli cognome string ROSSI Y Enter the customer's last name.
nome string MARIO Y Enter the customer's first name.
indirizzo string PIAZZA DUOMO, 1 Y Enter the customer's address.
cap string 20121 Y Enter the customer's postal code.
localita string MILANO Y Enter the customer's city.
provincia string MI Y Enter the abbreviation of the customer's Italian province.
N.B. For a foreign customer, fill in this field as follows: --
nazione string IT Y Enter the abbreviation of the customer's country, using the ISO 3166-1 Alpha-2 code (link).
email string mariorossi@gmail.com Y Enter the customer's email.
telefono string 0212345678 optional Enter the customer's phone number.
cellulare string 3470123456 optional Enter the customer's mobile phone number.
ragionesociale string ROSSI MARIO SLRS optional Enter the customer's company name, if any.
codicefiscale string RSSMRA11A11A111A Y Enter the customer's tax code.
partitaiva string 01234567890 optional Enter the customer's VAT number, if any.
N.B. Mandatory field if the ragionesociale field is filled in.
fe_pec string marirossi@pec.it optional Enter the customer's PEC, if any.
N.B. Mandatory field if the ragionesociale field is filled in (not mandatory for a foreign customer).
fe_sdi string 0000000 Y Enter the customer's SDI, if any (enter 0000000 for a private individual).
banca string CREDITO EMILIANO SPA optional Enter the name of the customer's bank.
iban string IT1A12341234123412341234123 optional Enter the customer's IBAN, if any.
N.B. Field required for cash-on-delivery remittance.
intestazioneconto string ROSSI MARIO optional Enter the exact name of the holder of the customer's bank account.
username string mariorossi Y Enter the customer's login username.
password string 12345678 Y Enter the customer's login password.

JSON Response

{
	"result":"OK",
	"errorcode":0,
	"errormessage":"NEWCUSTOMER OK",
	"id_dva":3723,
	"timestamp":"2024-01-19 09:31:59"
	"version":"1.1.20"}

Notes on the JSON response:

The JSON response contains the id_dva field, which is the new ID of the created customer, to be used for subsequent calls.

AddFund

The addfund call allows you to transfer prepaid credit from the group leader's master account to the customer's account.

Example of addfund call in PHP:

$ch = curl_init("https://api.easyparcel.it/addfund/c2fbbf11fdb3b18a20d543eeebdb057232c9c20b9ce850d60ce74ec36b0a8a77");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonRequest);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
	'Content-Type: application/json',
	'Content-Length: ' . strlen($jsonRequest))
);
$jsonResult = curl_exec($ch);

JSON Request

{
	"call":"addfund",
	"dettagli":{
		"idcustomer":3723,
		"amount":100.00
	}
}

JSON Request Requirements

Level 1 Level 2 Type Example Mandatory Description
call   string addfund Y Enter addfund
dettagli idcustomer numeric 3723 Y Enter the ID of the customer to transfer the funds to.
amount decimal 100.00 Y Enter the amount to transfer to the customer. The group leader's master credit must be greater than or equal to the amount to transfer to the customer. In case of a decimal amount, use the DOT and not the COMMA as the decimal separator.

JSON Response

{
	"result":"OK",
	"errorcode":0,
	"errormessage":"ADDFUND OK",
	"timestamp":"2024-01-19 09:31:59",
	"version":1.1.14}

Balance

The balance call allows you to obtain the remaining credit value of the master account and, optionally, of the customer specified in the call.

Example of balance call in PHP:

$ch = curl_init("https://api.easyparcel.it/balance/c2fbbf11fdb3b18a20d543eeebdb057232c9c20b9ce850d60ce74ec36b0a8a77");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonRequest);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
	'Content-Type: application/json',
	'Content-Length: ' . strlen($jsonRequest))
);
$jsonResult = curl_exec($ch);

JSON Request

{
	"call":"balance",
	"dettagli":{
		"idcustomer":3723
	}
}

JSON Request Requirements

Level 1 Level 2 Type Example Mandatory Description
call   string balance Y Enter balance
dettagli idcustomer numeric 3723 optional Optionally enter the ID of the customer whose remaining credit you want to check.

JSON Response

{
	"result":"OK",
	"errorcode":0,
	"errormessage":"BALANCE OK",
	"balance_master":245.90,
	"balance_customer":23.75,
	"timestamp":"2024-01-19 09:31:59",
	"version":1.1.14}

Notes on the JSON response:

The JSON response always contains the balance_master field, which is the remaining credit of the master account, and contains the balance_customer field only if the dettagli->idcustomer field was specified in the request.

PUDO

The pudo call allows you to search for available pickup and delivery points for PDB (Poste Delivery Business) and INPOST carriers.

Example pudo call in PHP:

$ch = curl_init("https://api.easyparcel.it/pudo/YOUR_API_KEY");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonRequest);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-Type: application/json',
    'Content-Length: ' . strlen($jsonRequest))
);
$jsonResult = curl_exec($ch);

JSON Request - PDB example (search by province)

{
    "carrier": "PDB",
    "province": "MI",
    "type": "FMP",
    "limit": 50
}

JSON Request - INPOST example (search by radius from postal code)

{
    "carrier": "INPOST",
    "postal_code": "20121",
    "radius": 15,
    "limit": 20
}

JSON Request - Example with GPS coordinates

{
    "carrier": "INPOST",
    "lat": 45.4642,
    "lon": 9.1900,
    "radius": 5,
    "limit": 10
}

JSON Request Parameters

Parameter Type PDB INPOST Required Description
carrier string ✓ ✓ Y PDB or INPOST
postal_code string ✓ ✓ N Postal code. If specified with radius, used as center for geographic search. Otherwise filters by exact postal code.
province string ✓ ✓ N Province abbreviation (e.g. MI, RM)
city string ✓ ✓ N City name (partial search)
search string ✓ ✓ N Free text search on code, name, address
radius number ✓ ✓ N Search radius in km (default: 10). Requires postal_code or lat/lon.
lat number ✓ ✓ N Reference point latitude (alternative to postal code for geographic search)
lon number ✓ ✓ N Reference point longitude
type string ✓ ✓ N PDB: FMP (Post Office), APT (Punto Poste), RTZ (Poste Locker)
INPOST: parcel_locker
status string   ✓ N INPOST only. Default: Operating. Filter by point status.
location_type string   ✓ N INPOST only. Indoor or Outdoor.
locale string ✓ ✓ N it (default) or en. Translates field names in the response.
limit number ✓ ✓ N Maximum number of results (default: 100, max: 1000)

JSON Response - PDB

{
    "result": "OK",
    "carrier": "PDB",
    "count": 2,
    "points": [
        {
            "code": "005640",
            "type": "FMP",
            "name": "MILANO 35",
            "address": "VIA OSCAR WILDE 2",
            "city": "MILANO",
            "postal_code": "20154",
            "province": "MI",
            "latitude": 45.4874,
            "longitude": 9.1726,
            "distance_km": 1.23
        }
    ]
}

JSON Response - INPOST

{
    "result": "OK",
    "carrier": "INPOST",
    "count": 2,
    "points": [
        {
            "code": "ITMIL089426D",
            "status": "Operating",
            "postal_code": "20121",
            "city": "Milano",
            "province": "MI",
            "address": "Via Torino",
            "latitude": 45.4631,
            "longitude": 9.1882,
            "type": "parcel_locker",
            "location_type": "Indoor",
            "distance_km": 0.54
        }
    ]
}

Notes on the JSON response:

  • The distance_km field is present only when the search was performed by geographic radius (via postal_code with radius, or lat/lon). Results are sorted by ascending distance.
  • For PDB the types are: FMP (Post Office), APT (Punto Poste), RTZ (Poste Locker).
  • For INPOST points with status other than Operating are not active and cannot be used for shipments.
  • The codes returned in the code field are the ones to use in the pudo_mittente and pudo_destinatario fields of the order-fast call.
  • For INPOST both pudo_mittente and pudo_destinatario fields are required and must be different from each other.

CheckCoupon

The checkcoupon call allows you to verify the correct applicability of the discount coupon to a shipment.

Example of checkcoupon call in PHP:

$ch = curl_init("https://api.easyparcel.it/checkcoupon/c2fbbf11fdb3b18a20d543eeebdb057232c9c20b9ce850d60ce74ec36b0a8a77");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonRequest);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
	'Content-Type: application/json',
	'Content-Length: ' . strlen($jsonRequest))
);
$jsonResult = curl_exec($ch);

JSON Request

{
	"call":"checkcoupon",
	"dettagli":{
		"idcustomer":3723,
		"vettore":"UPS21S",
		"peso_totale":8.00,
		"tipo_spedizione":"E",
		"cosa_spedire":"M",
		"provincia":"RM",
		"nazione":"US",
		"coupon" => "ILOVEUSA21"
	}
}

JSON Request Requirements

Level 1 Level 2 Type Example Mandatory Description
call   string checkcoupon Y Enter checkcoupon
dettagli idcustomer numeric 3723 Y Enter the ID of the customer who owns the coupon.
vettore string UPS21S Y Enter the carrier code.
peso_totale string 8.00 Y Enter the total weight of the shipment.
tipo_spedizione string N Y N = domestic
E = foreign
I = import
cosa_spedire string M Y D = documents
M = goods/parcels
P = pallets
provincia string RM Y Enter the code of the Italian province of origin of the shipment.
Note: In case of import, indicate the Italian province of destination.
nazione string US Y Enter the code of the destination country of the shipment.
Note: In case of import, indicate the country of origin.
coupon string ILOVEUSA21 Y Enter the code of the coupon to apply to the shipment.

JSON Response

{
	"result":"OK",
	"errorcode":0,
	"errormessage":"CHECKCOUPON OK",
	"errordetails":"Previsto sconto del 5%",
	"timestamp":"2024-01-19 09:31:59",
	"version":"1.1.20"}

Notes on the JSON response:

The JSON response always contains the errorcode field, which indicates whether the coupon is valid or not, while the errodetails field reports the value of the coupon or the type of error.

Errors

This section contains the list and meaning of all the possible errors that API calls to the system may return.

Example of JSON error response

{
	"result" => "KO",
	"errorcode" => "110",
	"errormessage" => "JSON - Errore sui campi",
	"errordetails" => "Campo 'mittente->cap' mancante o non corretto",
	"timestamp":"2024-01-19 09:31:59"
}

Notes on the JSON response:

The system responds with an HTTP_RESPONSE_CODE through the PHP function http_response_code. A 200 response identifies a successful response, while a 400 response identifies the detection of an error.
In case of an error, the API function returns a JSON that contains the details of the error, so that it is possible to identify and fix them.

Error codes table

ErrorCode ErrorMessage Description
NESSUN ERRORE The operation was completed successfully.
APIKEY - Non valida The APIKEY code used in the call is not a valid key.
APIKEY - Chiave scaduta The APIKEY code used in the call has expired and needs to be renewed in order to keep working.
APIKEY - Servizio non disponibile per questo indirizzo IP The call comes from an IP address that is not authorized for this APIKEY code.
APIKEY - Limite giornaliero chiamate superato The call has exceeded the daily limit for this APIKEY code.
JSON - Manca il file The JSON file that must be passed to the function via POST is missing.
JSON - Errore sui campi The JSON file passed does not meet the requirements for the call. The errordetails field details the incorrect or missing values.
USER Credito esaurito The remaining credit does not allow the purchase to be completed.
ORDER Già memorizzato The offer code has already been processed and therefore the purchase cannot be duplicated. Purchase not completed.
ORDER Errore in fase di memorizzazione The purchase could not be saved. Purchase not completed. Contact support.
ORDER Errore in fase di memorizzazione (2) The purchase could not be saved because a carrier was selected that does not currently allow a purchase via API. Purchase not completed.
NEWCUSTOMER Funzione non disponibile Function not available for this account.
NEWCUSTOMER Errore in fase di memorizzazione The new customer could not be saved. Contact support.
ADDFUND Funzione non disponibile Function not available for this account.
ADDFUND Credito non sufficiente The master account does not have enough credit to top up the customer.
ADDFUND Cliente non corretto The specified customer does not exist or is not part of the network.
BALANCE Funzione non disponibile Function not available for this account.
BALANCE Cliente non corretto The specified customer does not exist or is not part of the network.