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-03-31 20:17:19"
	}
}

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

English translation in progress ...

La chiamata quotation consente di ottenere il preventivo di costo relativo ad una spedizione, secondo precisi parametri che vengono specificati. In pratica, necessitano alcuni dati relativi al luogo di partenza, al luogo di destinatazione e al tipo di spedizione (nazionale/internazionale, specifiche dei colli, ecc).
Il sistema Easy Parcel API calcolerà, se possibile, il costo di spedizione in base ai vettori standard del sistema oppure in base a quelli specificamente abilitati al cliente (ed agganciati alla sua ApiKey). Le risposte dettagliano il vettore utilizzato e gli eventuali servizi opzionali abilitabili (con i relativi costi).

Esempio di chiamata quotation 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);

Richiesta JSON

{
	"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"
	}
}

Requisiti della richiesta JSON

Livello 1 Livello 2 Livello 3 Tipo Esempio Obbligatorio Descrizione
call     string quotation S Inserire quotation
dettagli idcustomer   numeric 12345 optional In questo campo può essere indicato l'id del cliente del proprio network sul cui listino calcolare il preventivo.
tipo_spedizione   string N S N = nazionale
E = estero
I = import
cosa_spedire   string M S D = documenti
M = merce/pacchi
P = pallets
contenuto   string BISCOTTI S Inserire la descrizione del contenuto
accessori contrassegno_importo decimal 250.00 optional Indicare l'importo del contrassegno
Il servizio potrebbe non essere previsto per alcuni vettori
assicurazione_importo decimal 350.00 optional Indicare l'importo dell'assicurazione
Il servizio potrebbe non essere previsto per alcuni vettori
consegnaalpiano string S optional S = acquistare
N = non acquistare
Il servizio potrebbe non essere previsto per alcuni vettori
consegnasuappuntamento string S optional S = acquistare
N = non acquistare
Il servizio potrebbe non essere previsto per alcuni vettori
priornotice string S optional S = acquistare
N = non acquistare
Il servizio "Prior Notice" è acquistabile solo per spedizioni estere dirette negli USA
colli peso   decimal 3.000 S Peso complessivo di questa serie di colli, in kg
larghezza   integer 30 S Larghezza del singolo collo di questa serie di colli (in cm)
profondita   integer 20 S Profondità del singolo collo di questa serie di colli (in cm)
altezza   integer 15 S Altezza del singolo collo di questa serie di colli (in cm)
nr_colli   integer 1 S Numero di colli con stesse dimensioni di questa serie di colli
mittente cap   string 00175 S CAP del mittente
localita   string ROMA S Località del mittente
provincia   string RM S Provincia del mittente
nazione   string IT S Inserire IT
destinatario cap   string 20121 S CAP del destinatario
localita   string MILANO S Località del destinatario
provincia   string MI S Provincia del destinatario, se spedizione internazionale inserire --
country   string IT Obbligatorio solo su internazionale verso USA e Canada Country del destinatario, da valorizzare solo per USA (link) e Canada (link)
nazione   string IT S Nazione del destinatario, usare il codice ISO 3166-1 Alpha-2 (link)

Risposta JSON

{
	"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-03-31 20:17:19",
	"version":"1.1.20"
}

Note sulla risposta JSON:

La risposta JSON contiene un array di quotazioni offerte dai vari Vettori collegati al sistema Easy Parcel API. Ogni offerta viene identificata da un codice_offerta che dev'essere successivamente utilizzata nella chiamata di tipo "order" per identificare il preventivo da acquistare la spedizione. Per ogni offerta viene restituito il vettore di riferimento, il suo logo, l'importo dovuto e anche una serie di informazioni aggiuntive relative ad eventuali servizi opzionali che possono essere richiesti.

Order

English translation in progress ...

La chiamata order concretizza l'ordine di una spedizione, secondo le specifiche di un precedente preventivo (quotation) che dev'essere indicato come codice_offerta di riferimento.
Per poter perfezionare l'ordine è necessario specificare ulteriori dati obbligatori relativi ai nominativi di mittente e destinatario e alla specifica degli eventuali servizi opzionali richiesti, le cui offerte sono contenute nella richiamata "quotation".
Il sistema Easy Parcel API rielaborerà il tutto, verificando preventivamente la capienza economica del credito prepagato. Il caso di esito positivo, i costi verranno addebitati sul credito prepagato e viene generato l'ordine che verrà trasmesso al centro di elaborazione per le successive fasi di gestione (invio email di conferma, generazione lettera di vettura, ecc).

Esempio di chiamata order 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);

Richiesta JSON

{
	"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-03-31",
			"disponibile_ora":"08:00",
			"ritiro_mattina_dalle":"08:00",
			"ritiro_mattina_alle":"12:00",
			"ritiro_pomeriggio_dalle":"14:00",
			"ritiro_pomeriggio_alle":"18:00"
		}
	}
}

Requisiti della richiesta JSON

Livello 1 Livello 2 Livello 3 Tipo Esempio Obbligatorio Descrizione
call     string order S Inserire order
dettagli codice_offerta   string 5dcc4a53b00fc S Inserire un codice_offerta fra quelli ricevuti in risposta alla precedente chiamata "quotation"
note_cliente   string ACQUISTO DI TEST optional Inserire un testo di descrizione dell'acquisto
custom   string XYZ123456 optional Campo custom a testo libero per eventuale ricerca ordine
coupon   string ILOVEUSA21 optional Inserire il codice di un eventuale coupon di sconto.
N.B. Il coupon dovrebbe prima essere verificato con la chiamata CheckCoupon.
accessori contrassegno string S optional S = acquistare
N = non acquistare
Il servizio potrebbe non essere previsto per alcuni vettori
assicurazione string S optional S = acquistare
N = non acquistare
Il servizio potrebbe non essere previsto per alcuni vettori
consegnaalpiano string S optional S = acquistare
N = non acquistare
Il servizio potrebbe non essere previsto per alcuni vettori
consegnasuappuntamento string S optional S = acquistare
N = non acquistare
Il servizio potrebbe non essere previsto per alcuni vettori
trackingavanzato string S optional S = acquistare
N = non acquistare
priornotice string S optional S = acquistare
N = non acquistare
Il servizio "Prior Notice" è acquistabile solo per spedizioni estere dirette negli USA
mittente nominativo   string Rossi Mario S Nominativo del mittente
indirizzo   string Via del Colosseo, 1 S Indirizzo del mittente
email   string mario@rossi.it S Indirizzo email del mittente
telefono   string 0611111111 optional Telefono fisso del mittente
cellulare   string 3471111111 S Cellulare del mittente
contatto   string Rossi Mario S Contatto del mittente
codicefiscale   string RSSMRA80A01H501U S Codice fiscale del mittente
destinatario nominativo   string Verdi Giuseppe S Nominativo del destinatario
indirizzo   string Piazza Duomo, 1 S Indirizzo del destinatario
email   string giuseppe@verdi.it S Indirizzo email del destinatario
telefono   string 0222222222 optional Telefono fisso del destinatario
cellulare   string 34722222222 S Cellulare del destinatario
contatto   string Verdi Giuseppe S Contatto del destinatario
codicefiscale   string VRDGPP80A01H501U optional Codice fiscale del mittente
ritiro prenotazione   string S optional S = richiesto
N = non richiesto
Il servizio consiste nel ritiro della spedizione presso il mittente.
dettagli ritirodove string M S M = presso l'indirizzo del Mittente
P = presso l'indirizzo del Point, indicato nel campo idcustomer della chiamata quotation.
disponibile_dal date 2026-03-31 S Data (nel formato AAAA-MM-DD) che identifica da quando la spedizione è disponibile per essere ritirata.
disponibile_ora time 08:00 S Orario (nel formato HH:MM) che identifica da quando la spedizione è disponibile per essere ritirata.
ritiro_mattina_dalle time 08:00 S Orario (nel formato HH:MM) che identifica da quando la spedizione è disponibile per essere ritirata.
ritiro_mattina_alle time 12:00 S Orario (nel formato HH:MM) che identifica da quando la spedizione è disponibile per essere ritirata.
ritiro_pomeriggio_dalle time 14:00 S Orario (nel formato HH:MM) che identifica da quando la spedizione è disponibile per essere ritirata.
ritiro_pomeriggio_alle time 18:00 S Orario (nel formato HH:MM) che identifica da quando la spedizione è disponibile per essere ritirata.

Risposta JSON

{
	"result":"OK",
	"errorcode":"0",
	"errormessage":"ACQUISTO OK",
	"codice_offerta":"5dcc4a53b00fc",
	"custom":"XYZ123456",
	"ordine":"EAS-5dcc4a53b00fc",
	"id_ordine":"1234567",
	"importo":"6.90",
	"timestamp":"2026-03-31 20:17:19",
	"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 = Europe, I = International
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.
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-03-31 20:17:19",
	"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.

GetOrder

English translation in progress ...

La chiamata getorder consente di visualizzare tutte le informazioni relative ad un ordine di una spedizione e può essere ricercato per codice_offerta oppure per custom.

Esempio di chiamata getorder 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);

Richiesta JSON

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

Requisiti della richiesta JSON

Livello 1 Livello 2 Tipo Esempio Obbligatorio Descrizione
call   string getorder S Inserire getorder
dettagli codice_offerta string 5dcc4a53b00fc optional Inserire un codice_offerta fra quelli ricevuti in risposta ad una precedente chiamata "order".
N.B. Se non inserito, diventa obbligatorio il campo custom.
custom string XYZ123456 optional Inserire un custom fra quelli indicati in una precedente chiamata "order".
N.B. Se non inserito, diventa obbligatorio il campo codice_offerta.

Risposta JSON

{
	"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-03-31 20:17:19",
	"version":"1.1.20"
}

Note sulla risposta JSON:

La risposta JSON contiene tutti i dati relativi alla memorizzazione dell'ordine

ListOrder

English translation in progress ...

La chiamata listorder consente di ottenere una lista di spedizioni filtrate per il periodo scelto e/o id utente.

Esempio di chiamata listorder 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);

Richiesta JSON

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

Requisiti della richiesta JSON

Livello 1 Livello 2 Tipo Esempio Obbligatorio Descrizione
call   string listorder S Inserire listorder
dettagli data_inizio string 2024-01-01 optional Inserire una data di inizio periodo nel formato AAAA-MM-GG.
N.B. Se non inserita, viene considerata la data odierna.
data_fine string 2024-01-15 optional Inserire una data di fine periodo nel formato AAAA-MM-GG.
N.B. Se non inserita, viene considerata la data odierna.
idcustomer numeric 12345 optional Inserire l'ID di un utente sotto la propria rete.
N.B. Se non inserito, viene mostrata la lista di tutti gli ordini.
paginazione numeric 25 optional Inserire la dimensione della paginazione ossia il numero di ordini che verranno restituiti dalla chiamata.
N.B. Se non inserito, viene mostrata la lista dei primi 10 ordini; la massima paginazione è di 100 ordini.
pagina numeric 2 optional Inserire il numero della pagina da visualizzare.
N.B. Se non inserito, viene mostrata la prima pagina della lista degli ordini.

Risposta JSON

{
	"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"
}

Note sulla risposta JSON:

La risposta JSON contiene la lista paginata degli ordini del periodo scelto ed eventualmente per l'utente selezionato, con alcuni dati identificativi di ogni ordine.

Tracking

English translation in progress ...

La chiamata tracking permette di ottenere il link per consultare il tracking di una spedizione, che può essere ricercata per codice_offerta, per custom oppure tramite ldv.

Esempio di chiamata tracking 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);

Richiesta JSON

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

Requisiti della richiesta JSON

Livello 1 Livello 2 Tipo Esempio Obbligatorio Descrizione
call   string tracking S Inserire tracking
dettagli codice_offerta string 5dcc4a53b00fc optional Inserire un codice_offerta fra quelli ricevuti in risposta ad una precedente chiamata "order".
N.B. E' obbligatorio indicare un codice_offerta, un custom oppure una ldv.
custom string XYZ123456 optional Inserire un custom fra quelli indicati in una precedente chiamata "order".
N.B. E' obbligatorio indicare un codice_offerta, un custom oppure una ldv.
ldv string 288016E049120 optional Inserire una ldv da ricercare.
N.B. E' obbligatorio indicare un codice_offerta, un custom oppure una ldv.

Risposta JSON

{
	"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"
}

Note sulla risposta JSON:

La risposta JSON contiene tutti i dati relativi al tracking della spedizione e per il vettore SDA è disponibile anche tutto il dettaglio nell'apposito campo.

NewCustomer

English translation in progress ...

La chiamata newcustomer permette di creare un nuovo utente del proprio network.

Esempio di chiamata newcustomer 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);

Richiesta JSON

{
	"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"
	}
}

Requisiti della richiesta JSON

Livello 1 Livello 2 Tipo Esempio Obbligatorio Descrizione
call   string newcustomer S Inserire newcustomer
dettagli cognome string ROSSI S Inserire il cognome del cliente.
nome string MARIO S Inserire il nome del cliente.
indirizzo string PIAZZA DUOMO, 1 S Inserire l'indirizzo del cliente.
cap string 20121 S Inserire il cap del cliente.
localita string MILANO S Inserire la località del cliente.
provincia string MI S Inserire la sigla della provincia italiana del cliente.
N.B. In caso di cliente estero, compilare questo campo come segue: --
nazione string IT S Inserire la sigla della nazione del cliente, usando il codice ISO 3166-1 Alpha-2 (link).
email string mariorossi@gmail.com S Inserire l'email del cliente.
telefono string 0212345678 optional Inserire il numero di telefono del cliente.
cellulare string 3470123456 optional Inserire il numero di cellulare del cliente.
ragionesociale string ROSSI MARIO SLRS optional Inserire l'eventuale ragione sociale del cliente.
codicefiscale string RSSMRA11A11A111A S Inserire il codice fiscale del cliente.
partitaiva string 01234567890 optional Inserire l'eventuale partita Iva del cliente.
N.B. Campo obbligatorio se compilato il campo ragionesociale.
fe_pec string marirossi@pec.it optional Inserire l'eventuale PEC del cliente.
N.B. Campo obbligatorio se compilato il campo ragionesociale (non obbligatorio per cliente estero).
fe_sdi string 0000000 S Inserire l'eventuale SDI del cliente (inserire 0000000 per privato).
banca string CREDITO EMILIANO SPA optional Inserire il nome della banca del cliente.
iban string IT1A12341234123412341234123 optional Inserire l'eventuale IBAN del cliente.
N.B. Campo necessario per rimessa contrassegni.
intestazioneconto string ROSSI MARIO optional Inserire il nome esatto dell'intestazione del conto bancario del cliente.
username string mariorossi S Inserire la username di accesso del cliente.
password string 12345678 S Inserire la password di accesso del cliente.

Risposta JSON

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

Note sulla risposta JSON:

La risposta JSON contiene il campo id_dva che è il nuovo ID del cliente creato, da utilizzare per successive chiamate.

AddFund

English translation in progress ...

La chiamata addfund permette di trasferire del credito prepagato dal conto master del capofila a quello del cliente.

Esempio di chiamata addfund 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);

Richiesta JSON

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

Requisiti della richiesta JSON

Livello 1 Livello 2 Tipo Esempio Obbligatorio Descrizione
call   string addfund S Inserire addfund
dettagli idcustomer numeric 3723 S Inserire l'ID del cliente al quale girare i fondi.
amount decimal 100.00 S Inserire l'importo da girare al cliente. Il credito master del capofila deve essere maggiore o uguale all'importo da girare al cliente. In caso di importo decimale, utilizzare il PUNTO e non la VIRGOLA come separatore decimale.

Risposta JSON

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

Balance

English translation in progress ...

La chiamata balance permette di ottenere il valore del credito residuo del conto master ed eventualmente del cliente indicato nella chiamata.

Esempio di chiamata balance 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);

Richiesta JSON

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

Requisiti della richiesta JSON

Livello 1 Livello 2 Tipo Esempio Obbligatorio Descrizione
call   string balance S Inserire balance
dettagli idcustomer numeric 3723 optional Inserire eventualmente l'ID del cliente del quale si vuole conoscere il credito residuo.

Risposta JSON

{
	"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}

Note sulla risposta JSON:

La risposta JSON contiene sempre il campo balance_master che è il credito residuo del capofila e contiene il campo balance_customer solo se nella richiesta è stato indicato il campo dettagli->idcustomer.

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

English translation in progress ...

La chiamata checkcoupon consente di verificare la corretta applicabilità del coupon sconto ad una spedizione.

Esempio di chiamata checkcoupon 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);

Richiesta JSON

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

Requisiti della richiesta JSON

Livello 1 Livello 2 Tipo Esempio Obbligatorio Descrizione
call   string checkcoupon S Inserire checkcoupon
dettagli idcustomer numeric 3723 S Inserire l'ID del cliente proprietario del coupon.
vettore string UPS21S S Inserire il codice del vettore.
peso_totale string 8.00 S Inserire il peso complessivo della spedizione.
tipo_spedizione string N S N = nazionale
E = estero
I = import
cosa_spedire string M S D = documenti
M = merce/pacchi
P = pallets
provincia string RM S Inserire la sigla della provincia italiana di partenza della spedizione.
N.B. In caso di import indicare la provincia italiana di destinazione.
nazione string US S Inserire la sigla della nazione di destinazione della spedizione.
N.B. In caso di import indicare la nazione di partenza.
coupon string ILOVEUSA21 S Inserire il codice del coupon da applicare alla spedizione.

Risposta JSON

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

Note sulla risposta JSON:

La risposta JSON contiene sempre il campo errorcode che indica se il coupon è valido o meno, mentre il campo errodetails riporta il valore del coupon oppure il tipo di errore.

Errors

English translation in progress ...

Questa sezione contiene l'elenco e il significato di tutti gli eventuali errori che le chiamate API al sistema restituiscono.

Esempio di risposta JSON di errore

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

Note sulla risposta JSON:

Il sistema risponde con un HTTP_RESPONSE_CODE attraverso la funzione PHP http_response_code. La risposta 200 identifica una risposta positiva, mentre una risposta 400 identifica l'individuazione di un errore.
In caso di errore, la funzione API restituisce un JSON che contiene i dettagli dell'errore, in modo che sia possibile identificarli e porvi rimedio.

Tabella dei codici di errore

ErrorCode ErrorMessage Descrizione
NESSUN ERRORE L'operazione è stata eseguita correttamente.
APIKEY - Non valida Il codice APIKEY utilizzato nella chiamata non risulta una chiave valida.
APIKEY - Chiave scaduta Il codice APIKEY utilizzato nella chiamata è scaduto e necessita del rinnovo per poter continuare a funzionare.
APIKEY - Servizio non disponibile per questo indirizzo IP La chiamata proviene da un indirizzo IP non autorizzato per questo codice APIKEY.
APIKEY - Limite giornaliero chiamate superato La chiamata ha superato il limite giornaliero per questo codice APIKEY.
JSON - Manca il file Manca il file JSON che dev'essere passato alla funzione via POST.
JSON - Errore sui campi Il file JSON passato non rispetta i requisiti per la chiamata. Nel campo errordetails sono dettagliati i valori errati o mancanti.
USER Credito esaurito Il credito residuo non consente di perfezionare l'acquisto.
ORDER Già memorizzato Il codice offerta è già stato elaborato e quindi l'acquisto non è duplicabile. Acquisto non perfezionato.
ORDER Errore in fase di memorizzazione La memorizzazione dell'acquisto non è andata a buon fine. Acquisto non perfezionato. Contattare l'assistenza.
ORDER Errore in fase di memorizzazione (2) La memorizzazione dell'acquisto non è andata a buon fine perché è stato selezionato un vettore che al momento non consente un acquisto via API. Acquisto non perfezionato.
NEWCUSTOMER Funzione non disponibile Funzione non disponibile per questo account.
NEWCUSTOMER Errore in fase di memorizzazione La memorizzazione del nuovo cliente non è andata a buon fine. Contattare l'assistenza.
ADDFUND Funzione non disponibile Funzione non disponibile per questo account.
ADDFUND Credito non sufficiente L'account master non ha credito sufficiente per ricaricare il cliente.
ADDFUND Cliente non corretto Il cliente indicato non esiste o non fa parte del network.
BALANCE Funzione non disponibile Funzione non disponibile per questo account.
BALANCE Cliente non corretto Il cliente indicato non esiste o non fa parte del network.